mcp-zoekt

An MCP (Model Context Protocol) server that enables AI coding assistants to search code across indexed repositories using Zoekt.

Overview

This repository provides:

• zoekt-mcp/ - TypeScript MCP server that connects AI assistants (GitHub Copilot, Claude, etc.) to Zoekt
• docker/ - Docker Compose infrastructure for self-hosting Zoekt with working-tree indexing and GitHub organization mirroring (including multi-org)
• zoekt/ - Git submodule reference to sourcegraph/zoekt

Quick Start

1. Start Zoekt Infrastructure

cd docker

# Create a .env from the template and choose a mode via COMPOSE_PROFILES
cp .env.example .env

# For GitHub mode only: create config directory and add your GitHub token
# mkdir -p config
# echo "ghp_your_token_here" > config/github-token.txt

# Start services
docker compose up -d

2. Configure Your AI Assistant

VS Code with GitHub Copilot - Add to .vscode/settings.json:

{
  "github.copilot.chat.experimental.mcpServers": {
    "zoekt": {
      "command": "npx",
      "args": ["mcp-zoekt", "--url", "http://localhost:6070"]
    }
  }
}

Claude Desktop - Add to your config file:

{
  "mcpServers": {
    "zoekt": {
      "command": "npx",
      "args": ["mcp-zoekt", "--url", "http://localhost:6070"]
    }
  }
}

3. Search Your Code

Ask your AI assistant to search across your indexed repositories:

"Search for authentication middleware in my codebase" "Find all usages of the UserService class" "Show me how error handling is implemented"

MCP Tools

Tool	Description
search	Search code using Zoekt query syntax (regex, file filters, language filters)
search_symbols	Find symbol definitions (functions, classes, methods) with optional kind filtering
search_files	Search for files by filename pattern
find_references	Find all definitions and usages of a symbol across repositories
list_repos	List all indexed repositories with optional filtering
file_content	Retrieve full file contents from indexed repositories
get_health	Check health status of MCP server and Zoekt backend

Documentation

• MCP Server Documentation - Detailed MCP server usage and configuration
• Docker Setup - Infrastructure setup and configuration options

Development

# Install dependencies
cd zoekt-mcp
npm install

# Run tests
npm test              # Unit tests
npm run test:all      # All tests (requires Docker infrastructure)

# Build
npm run build

License

Apache License 2.0 - see LICENSE for details.

This project uses Zoekt which is also licensed under Apache 2.0 by Sourcegraph.