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:

  bash

  Copy

  # 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 Desktop or engine works. You need Docker anyway for the backend, so this path saves you from installing uv if you don't already have it.

And for the backend:

• Docker with Compose v2 — runs zoekt-webserver and the one-shot indexer via the compose file attached to every release.

1. Start the backend (once per machine)

The zoekt backend is a regular Docker Compose stack you run yourself — zoekt-mcp does not lifecycle-manage it. Grab the compose file and helper script from the latest GitHub release and bring them up against whatever directory holds your code:

# Fetch the two files you need from the latest release.
mkdir -p ~/.zoekt-mcp && cd ~/.zoekt-mcp
curl -LO https://github.com/radiovisual/zoekt-mcp/releases/latest/download/docker-compose.yml
curl -LO https://github.com/radiovisual/zoekt-mcp/releases/latest/download/index.sh
chmod +x index.sh

# Point the indexer at any parent directory on your machine.
# Every top-level subdirectory becomes one searchable repo.
echo "ZOEKT_REPOS_DIR=/home/you/code" > .env

# Bring up zoekt-webserver + the one-shot indexer.
docker compose up -d

So if /home/you/code looks like this:

~/code/
├── project-a/       → indexed as zoekt repo "project-a"
├── project-b/       → indexed as zoekt repo "project-b"
└── scratch-notes/   → indexed as zoekt repo "scratch-notes"

…zoekt indexes all three repos in one pass and you can scope any query with repo:project-a — or leave repo: off to search across everything at once. See Indexing multiple codebases below for more on the one-server-many-repos model.

Sanity check:

curl -s -XPOST -d '{"Q":"repo:."}' http://localhost:6070/api/list \
  | python3 -m json.tool | head -20

You should see each subdirectory of ZOEKT_REPOS_DIR listed as a zoekt repo.

On macOS / Windows Docker Desktop, the path you pick must be under an allowed file-sharing root (check Docker Desktop → Settings → Resources → File Sharing). On Linux there's no such restriction.

Just want to try it without touching your real code directory? Clone the repo and use the in-tree test fixture: ./tests/fixtures/up.sh — see Development at the bottom of this file.

2. Wire the MCP server into your client

Two install paths — pick whichever matches your existing tooling. Both end up running the same versioned server binary; the only difference is how it's launched.

Path A — uvx (recommended if you already have uv)

uvx downloads the latest zoekt-mcp from PyPI on first invocation, caches it, and spawns it. No permanent install, no venv to manage.

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "zoekt": {
      "type": "stdio",
      "command": "uvx",
      "args": ["zoekt-mcp"],
      "env": { "ZOEKT_URL": "http://localhost:6070" }
    }
  }
}

Or via the claude CLI:

claude mcp add zoekt \
    --env ZOEKT_URL=http://localhost:6070 \
    -- uvx zoekt-mcp

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "zoekt": {
      "command": "uvx",
      "args": ["zoekt-mcp"],
      "env": { "ZOEKT_URL": "http://localhost:6070" }
    }
  }
}

Cursor (~/.cursor/mcp.json or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "zoekt": {
      "command": "uvx",
      "args": ["zoekt-mcp"],
      "env": { "ZOEKT_URL": "http://localhost:6070" }
    }
  }
}

To pin a specific version instead of always using the latest:

"args": ["zoekt-mcp==0.1.0"]

Path B — Docker image (no Python tooling required)

If you already have Docker running for the backend and would rather not install uv, use the container image instead. MCP clients spawn it over stdio exactly like the uvx path.

Claude Code / Claude Desktop / Cursor:

{
  "mcpServers": {
    "zoekt": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--network=host",
        "-e", "ZOEKT_URL=http://localhost:6070",
        "ghcr.io/radiovisual/zoekt-mcp:latest"
      ]
    }
  }
}

On Docker Desktop (macOS/Windows) the host isn't reachable via localhost from inside a container. Drop --network=host and use host.docker.internal instead:

"args": [
  "run", "-i", "--rm",
  "-e", "ZOEKT_URL=http://host.docker.internal:6070",
  "ghcr.io/radiovisual/zoekt-mcp:latest"
]

To pin a specific version, replace :latest with the semver tag (e.g. :0.1.0). The image is multi-arch (linux/amd64 + linux/arm64), so it works on Apple Silicon and ARM Linux hosts without extra flags.

3. Restart the client

Restart Claude Code / Claude Desktop / Cursor and the three tools (search_code, list_repos, get_file) should appear. Try something like "where is getVideoId defined?" and watch it call search_code("sym:getVideoId").

Indexing multiple codebases

One zoekt-mcp server handles as many repos as you want — that's the default. Every top-level subdirectory of ZOEKT_REPOS_DIR becomes a separate searchable repo in one shared index. The search_code tool can scope to a subset with repo:NAME (regex matched against repo names) or leave repo: off to search across everything.

If your projects live under different parent directories (e.g. ~/work/ and ~/personal/), the simplest fix is to create a single "index root" directory with symlinks pointing at each project and set ZOEKT_REPOS_DIR to that index root. One server, one config, all repos searchable.

mkdir -p ~/.zoekt-root
ln -s ~/work/project-a       ~/.zoekt-root/project-a
ln -s ~/personal/side-thing  ~/.zoekt-root/side-thing

cd ~/.zoekt-mcp
echo "ZOEKT_REPOS_DIR=$HOME/.zoekt-root" > .env
docker compose up -d