zoekt

Zoekt MCP Server provides code search capabilities powered by a Zoekt-backed indexing engine. It exposes MCP tools that allow an AI assistant or client to perform full-text code searches across multiple repositories, discover repositories and their structure, and fetch file contents from indexed sources. The server is designed for integration with AI workflows, enabling context-aware search prompts and guided query construction through its built-in tools. To use it, configure a Zoekt instance URL via ZOEKT_API_URL and run the MCP server with UV as described in installation steps. The MCP tools include search for code queries, search_prompt_guide to generate effective search prompts tailored to a goal, and fetch_content to retrieve file content or directory listings from indexed repositories. These capabilities help AI agents locate relevant code patterns, understand repository layouts, and fetch exact snippets needed for analysis or response generation.

Prerequisites:

• A running Zoekt instance accessible via HTTP(S)
• Python 3.10+ installed
• Optional: UV for easier dependency management

Installation options:

Using UV (recommended):

1. Install dependencies and run the server using UV:

# Install dependencies and run the server
uv sync
uv run python src/main.py

Using pip:

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package in editable mode
pip install -e .

# Run the server
python src/main.py

Using Docker:

# Build the image
docker build -t zoekt-mcp .

# Run the container with default ports
docker run -p 8000:8000 -p 8080:8080 \
  -e ZOEKT_API_URL=http://your-zoekt-instance \
  zoekt-mcp

# Or run with custom ports
docker run -p 9000:9000 -p 9080:9080 \
  -e ZOEKT_API_URL=http://your-zoekt-instance \
  -e MCP_SSE_PORT=9000 \
  -e MCP_STREAMABLE_HTTP_PORT=9080 \
  zoekt-mcp

Prerequisites recap:

• A Zoekt endpoint reachable via ZOEKT_API_URL
• Python 3.10+ (and UV if using UV workflow)
• Optional: Docker installed if you prefer containerized deployment

Environment variables:

• ZOEKT_API_URL: URL to your Zoekt instance (e.g., http://localhost:8080)
• MCP_SSE_PORT: Port for Server-Sent Events endpoint (default 8000)
• MCP_STREAMABLE_HTTP_PORT: Port for HTTP content fetch endpoint (default 8080) Common issues:
• Ensure Zoekt is reachable from the MCP server (CORS, network access, and correct API path)
• If using Docker, map ports correctly and pass the Zoekt URL as an environment variable
• When using UV or pip, ensure dependencies are installed and Python path is correctly set
• Check that the MCP server is started with the correct working directory so it can locate src/main.py Configuration tip:
• Keep ZOEKT_API_URL secure and avoid exposing internal endpoints publicly without authentication if your deployment requires it.