mcp-zoekt

The mcp-zoekt MCP server bridges AI coding assistants with Zoekt, enabling fast, indexed code search across your repositories. It exposes a set of MCP tools (such as search, search_symbols, search_files, find_references, list_repos, file_content, and get_health) that your editor or assistant can call to perform code search queries against the Zoekt-backed index. To use it, run the server (commonly via npx mcp-zoekt --url http://localhost:6070) and configure your AI assistant to connect to the provided URL. Once running, you can issue commands like searching for code patterns with regex or language filters, locating symbol definitions, listing indexed repositories, retrieving file contents, or checking the health of the server and backend.

Typical workflows include:

• Searching for authentication patterns across indexed repos using Zoekt query syntax.
• Finding definitions of functions or classes with search_symbols, and then tracing references with find_references.
• Retrieving the contents of a file with file_content for inspection within your assistant’s responses.
• Verifying system health with get_health before performing large-scale searches.

Prerequisites:

• Node.js and npm installed (or use npx, which installs as needed).
• Access to the internet to fetch the MCP server package.
• Optional: Docker and Docker Compose if you want to run the Zoekt infrastructure locally (docker/ directory in the repo).

Installation steps:

1. Ensure Node.js and npm are installed. You can verify:
   • node -v
   • npm -v
2. Install or run the MCP server using npx (no global install required):
   • npx mcp-zoekt --url http://localhost:6070 This will launch the Zoekt-enabled MCP server and expose its API at the provided URL.
3. If you prefer to install locally via package.json (optional):
   • git clone https://github.com/jahales/mcp-zoekt.git
   • cd mcp-zoekt/zoekt-mcp
   • npm install
   • npm run build (if a build step is provided)
   • npm start or node dist/server.js (depending on project setup)
4. Optional: Start Zoekt infrastructure using the docker/ setup:
   • cd docker
   • cp .env.example .env
   • docker compose up -d
   • Ensure Zoekt is reachable at the expected URL for the MCP server (e.g., http://localhost:6070).

Tips and notes:

• The MCP server uses npx mcp-zoekt with a URL to the Zoekt backend. Make sure the Zoekt service is up and accessible before starting the MCP server.
• If you see network or connectivity issues, verify that the port (default 6070) is open and not consumed by another process.
• When running via Docker, ensure the Zoekt container has indexed repositories and that the mirror configuration is correct for your environment (GitHub org mirroring is supported).
• Environment variables you might configure include ZIP URLs or authentication tokens if your Zoekt setup requires access to private repositories; you can typically pass such details through your Zoekt configuration and container environment.
• For editor integrations, use the recommended MCP server URL (for example, http://localhost:6070) and reference the available tools (search, search_symbols, etc.) in your IDE or assistant configuration.