Zoekt MCP Server

A Model Context Protocol (MCP) server that provides code search capabilities powered by Zoekt, the indexed code search engine used by Sourcegraph.

Overview
Features
Prerequisites
Installation
Configuration
- Required Environment Variables
- Optional Environment Variables
Usage with AI Tools
- Cursor
MCP Tools
Development
- Linting and Formatting

Overview

This MCP server integrates with Zoekt, a text search engine optimized for code repositories. Zoekt provides trigram-based indexing for searches across large codebases, making it suitable for AI assistants that need to find and understand code patterns.

Features

Code Search: Search across codebases using Zoekt's trigram indexing
Advanced Query Language: Support for regex patterns, file filters, language filters, and boolean operators
Repository Discovery: Find repositories by name and explore their structure
Content Fetching: Browse repository files and directories
AI Integration: Designed for LLM integration with guided search prompts

Prerequisites

Zoekt Instance: You need access to a running Zoekt search server. See the Zoekt documentation for setup instructions.
Python 3.10+: Required for running the MCP server
UV (optional): Modern Python package manager for easier dependency management

Installation

Using UV (recommended)

# Install dependencies
uv sync

# Run the server
uv run python src/main.py

Using pip

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

# Install package
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

Configuration

Required Environment Variables

ZOEKT_API_URL: URL of your Zoekt search instance

Optional Environment Variables

MCP_SSE_PORT: SSE server port (default: 8000)
MCP_STREAMABLE_HTTP_PORT: HTTP server port (default: 8080)

Usage with AI Tools

Cursor

After running the MCP server, add the following to your .cursor/mcp.json file:

{
  "mcpServers": {
    "zoekt": {
      "url": "http://localhost:8080/zoekt/mcp/"
    }
   }
}

MCP Tools

This server provides three powerful tools for AI assistants:

🔍 search

Search across indexed codebases using Zoekt's advanced query syntax with support for regex, language filters, and boolean operators.

📖 search_prompt_guide

Generate a context-aware guide for constructing effective search queries based on your specific objective.

📂 fetch_content

Retrieve file contents or explore directory structures from indexed repositories.

Development

Linting and Formatting

# Check code style
uv run ruff check src/

# Format code
uv run ruff format src/

Zoekt