colgrep-mcp

Semantic and hybrid code search for coding agents, as a stdio MCP server wrapping the colgrep CLI. colgrep indexes a repository into code units (functions, classes, methods, Markdown sections) and ranks them with a ColBERT late-interaction model fused with keyword search; this package puts that in the agent's tool list, where it gets used instead of grep.

The full landing page — plugin installs for Claude Code, Codex and Agent Plugins 1.0 clients, troubleshooting, development — is the repository README.

Requirements

• colgrep ≥ 1.6 on PATH (cargo install colgrep, or see the next-plaid README); the first run downloads the embedding model.
• Python ≥ 3.11. With uv nothing else: uvx fetches Python if needed.

Run

One-off, resolved and cached by uvx on first start:

uvx colgrep-mcp

Installed once as a plain executable, with no per-start resolution:

uv tool install colgrep-mcp   # or: pipx install colgrep-mcp
colgrep-mcp

Either command is a stdio MCP server; register it in your client as such:

{
  "mcpServers": {
    "colgrep": {
      "command": "uvx",
      "args": ["colgrep-mcp"],
      "env": { "COLGREP_MCP_ROOT": "/path/to/the/repo/to/search" }
    }
  }
}

COLGREP_MCP_ROOT is the project searched when a tool call names no path; without it the server falls back to the client's first root, then to its working directory. COLGREP_MCP_BINARY names the colgrep binary when it is not on PATH. The other variables (COLGREP_MCP_TIMEOUT, COLGREP_MCP_TEXT_BUDGET, COLGREP_MCP_LOG_LEVEL) are documented in the repository README.

What the agent gets

Tools

Resources (colgrep://guide, colgrep://settings, colgrep://indexes, colgrep://status/{+path}, colgrep://errors) and prompts (explore, locate, impact, housekeeping) come with it; the guide resource teaches the agent how to compose queries.

License

GNU Affero General Public License v3.0 or later.