zoekt-mcp

An MCP server that exposes Sourcegraph Zoekt code search to any MCP-capable AI agent — Claude Code, Claude Desktop, Cursor, MCP Inspector, etc. — so the agent can run fast, indexed, regex/symbol-aware code search over your repositories regardless of the language you're working in.

• MCP server: Python, built on FastMCP, runs over stdio so clients can spawn it as a subprocess. Published to PyPI, ghcr.io, and listed in the official MCP Registry, so no clone is required to use it.
• Backend: a zoekt-webserver you run yourself via the Docker Compose file attached to every GitHub release — or point the MCP server at any existing zoekt-webserver you have lying around.
• Tools exposed: search_code, list_repos, get_file.

Architecture

flowchart LR
    subgraph Client["MCP client"]
        CC["Claude Code<br/>Claude Desktop<br/>Cursor, etc."]
    end

    subgraph Server["zoekt-mcp (Python)"]
        Tools["search_code<br/>list_repos<br/>get_file"]
    end

    subgraph Backend["Docker: zoekt backend"]
        Web["zoekt-webserver"]
        Idx[("zoekt index<br/>named volume")]
        Indexer["zoekt-indexer<br/>(one-shot)"]
    end

    Code[("Your code<br/>bind mount")]

    CC <-->|"stdio<br/>MCP protocol"| Tools
    Tools <-->|"HTTP JSON<br/>/api/search<br/>/api/list<br/>/print"| Web
    Web --> Idx
    Code --> Indexer
    Indexer --> Idx

How a single search flows through the system

sequenceDiagram
    actor You
    participant Claude as Claude Code
    participant MCP as zoekt-mcp
    participant Web as zoekt-webserver
    participant Idx as zoekt index

    You->>Claude: "where is getVideoId defined?"
    Claude->>MCP: search_code("sym:getVideoId")
    MCP->>Web: POST /api/search
    Web->>Idx: scan shards
    Idx-->>Web: matches + ctags symbols
    Web-->>MCP: raw JSON result
    Note over MCP: trim to {repo, file,<br/>line, text, symbols}
    MCP-->>Claude: shaped result
    Claude-->>You: "src/index.js:17 (function)"

Quickstart

Getting from "nothing installed" to "Claude can search my code" is three steps: install the MCP server, run the backend, wire it into your client. No git clone required in any of them.

Prerequisites

You need exactly one of these to run the MCP server, plus Docker for the backend:

• uv on your PATH — for the uvx zoekt-mcp install path. MCP clients spawn the server via uvx, so which uv must resolve in whatever shell your client launches processes in. Install once per machine:

  # Official installer (macOS / Linux)
  curl -LsSf https://astral.sh/uv/install.sh | sh
  
  # Homebrew
  brew install uv
  
  # pipx
  pipx install uv
  

  The installer drops uv and uvx into ~/.local/bin/ (Linux/macOS) or %USERPROFILE%\.local\bin\ (Windows). Verify with uv --version.

• …or Docker — for the docker run ghcr.io/radiovisual/zoekt-mcp install path. Any recent Docker

... View full README on GitHub