codebase-mcp

Let coding agents explore, search, and safely edit large repositories without loading whole files or directory trees into context.

codebase-mcp is a high-performance, local-first Model Context Protocol server written in Rust. It runs over stdio and gives an agent 25 precise tools for targeted reads, scoped search, Tree-sitter code intelligence, and structured edits, so the model spends its context window on answers, not on raw file dumps.

Everything runs on your machine. There is no external indexing service, no network calls, and no telemetry.

---

Highlights

• Targeted reads: read a line range, a few snippets, or a single symbol body instead of an entire file.
• Scoped search: literal or regex matching with glob filters and large-repo-friendly limits.
• Code intelligence: symbols, definitions, references, imports/exports, and call graphs via Tree-sitter (13 languages).
• Safe edits: create, edit, and delete with structured success/error metadata for auditing.
• Persistent index: LMDB path metadata with an optional Tantivy content sidecar, kept per workspace.
• Local-only: no external services, runs entirely over stdio.

---

Quick Start

1. Get the binary

Download a prebuilt binary (Windows): Grab the latest codebase-mcp-windows-x64.exe or codebase-mcp-windows-arm64.exe from the Releases page.

Build from source (all platforms, requires the Rust stable toolchain):

cargo build --release

The binary is written to:

• Windows: target/release/codebase-mcp.exe
• Linux/macOS: target/release/codebase-mcp

2. Add it to your MCP client

Register the binary as a stdio server with one command. Replace the path with your binary location.

Claude Code

claude mcp add codebase-mcp -- /path/to/codebase-mcp

OpenAI Codex CLI

codex mcp add codebase-mcp -- /path/to/codebase-mcp

Gemini CLI

gemini mcp add codebase-mcp -- /path/to/codebase-mcp

On Windows, use the full .exe path, for example C:\path\to\codebase-mcp.exe.

Prefer editing a config file, or using Cursor, Windsurf, Cline, Roo, or VS Code? See Client Configuration below.

---

Why codebase-mcp?

Coding agents waste context (and money) when they read more than they need. codebase-mcp keeps responses small and on-target:

Without it	With codebase-mcp
Read a 2,000-line file to inspect one function	read_symbol_body returns the function body plus signature only
Dump the whole tree to find a file	fuzzy_find / project_map return a scoped, bounded view
cat a file and grep it inline	text_search with paths, includes, and max_results
Multiple round trips to gather context	batch_tool_call bundles related calls into one request

The result: fewer tokens, faster turns, and answers grounded in the real repository.

---

Tools

25 tools, grouped by purpose. Each returns output in the standard MCP content array shape.

Files and Edits

Tool	Description
resolve_path	Normalize a path and return preflight accessibility metadata.
read_file_range	Read a file or line range with encoding detection and truncation metadata.
count_file_lines	Count lines in a text file with basic encoding and binary detection.
read_snippets	Read multiple file ranges in one request.
convert_file_format	Rewrite a file with normalized encoding and line endings.
create_file	Create or overwrite a file with optional parent creation, encoding, and line endings.
create_directory	Create a directory with optional parent creation and structured results.
delete_file	Delete a file with structured success and error metadata.
edit_file	Edit a file using replace, append, prepend, or find-replace modes.
file_summary	Return quick file metadata, binary detection, and a short preview.

Search and Workspace

Tool	Description
text_search	Search files or directories using literal or regex matching.
fuzzy_find	Fuzzy path and file-name search across one or more roots.
project_map	Build a tree view of a project with optional size metadata.
workspace_stats	Summarize file, line, and language counts for a workspace path.

Code Intelligence

Tool	Description
get_symbols	Extract Tree-sitter AST symbols from source files.
read_symbol_body	Read a symbol body with AST-first resolution and heuristic fallback.
find_definition	Find likely symbol definitions across the project.
find_references	Find symbol references across the project.
list_imports	List imports (Rust, JS/TS, Swift, Objective-C).
list_exports	List exports (Rust, JS/TS, Swift, Objective-C).
get_call_graph	List outbound calls made from a function or symbol.
compare_symbols	Compare two resolved symbols and return metadata plus a unified diff.

Data and Diagnostics

Tool	Description
peek_archive	List archive entries or read a file inside an archive.
server_health	Check server uptime and indexing health.
batch_tool_call	Run multiple tools sequentially in one request and flatten combined results.

---

Supported Languages

The AST-backed code-intelligence tools (get_symbols, read_symbol_body, find_definition, find_references, get_call_graph, compare_symbols) use Tree-sitter and support these languages:

Language	Extensions
Rust	.rs
C	.c
C++	.cc, .cpp, .cxx, .h, .hh, .hpp, .hxx, .inc, .inl
Go	.go
Java	.java
C#	.cs
PHP	.php
Ruby	.rb
JavaScript	.js, .jsx, .mjs, .cjs
TypeScript	.ts, .tsx
Python	.py
Swift	.swift
Objective-C	.m, .mm

list_imports and list_exports currently support a subset: Rust, JavaScript/TypeScript, Swift, and Objective-C. The file, search, and workspace tools (text_search, fuzzy_find, read_file_range, and others) work on any text file regardless of language. Files larger than 2 MB are skipped by the AST parser.

---

Example Tool Calls

Search Rust files with regex:

{
  "name": "text_search",
  "arguments": {
    "query": "TODO|FIXME",
    "paths": ["/workspace"],
    "mode": "regex",
    "includes": ["*.rs"],
    "max_results": 50
  }
}

Read multiple focused snippets in one call:

{
  "name": "read_snippets",
  "arguments": {
    "max_total_bytes": 24000,
    "requests": [
      { "path": "/workspace/src/main.rs", "start_line": 1, "end_line": 80 },
      { "path": "/workspace/src/lib.rs", "start_line": 1, "end_line": 60 }
    ]
  }
}

Read a symbol body with its signature:

{
  "name": "read_symbol_body",
  "arguments": {
    "symbol": "processPayment",
    "paths": ["/workspace/src"],
    "include_signature": true
  }
}

Batch related calls in one MCP round trip:

{
  "name": "batch_tool_call",
  "arguments": {
    "calls": [
      { "tool": "file_summary", "args": { "path": "/workspace/README.md" } },
      { "tool": "project_map", "args": { "path": "/workspace", "max_depth": 2 } }
    ]
  }
}

---

Client Configuration

Use the release binary as a stdio MCP server. On Windows, point command to the .exe file.

Claude Desktop

{
  "mcpServers": {
    "codebase-mcp": {
      "command": "C:\\path\\to\\codebase-mcp\\target\\release\\codebase-mcp.exe",
      "args": []
    }
  }
}

Cursor, Windsurf, Cline, Roo

{
  "mcpServers": {
    "codebase-mcp": {
      "command": "/absolute/path/to/codebase-mcp/target/release/codebase-mcp",
      "args": []
    }
  }
}

VS Code MCP

{
  "servers": {
    "codebase-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/codebase-mcp/target/release/codebase-mcp",
      "args": []
    }
  }
}

---

Runtime Configuration

Variable	Purpose
CODEBASE_MCP_INDEX_DIR	Overrides the persistent index cache directory.
CODEBASE_MCP_TANTIVY_ENABLED	Enables the Tantivy content sidecar. Defaults to true.

Built-in defaults and workspace handling

Chromium-sized defaults are built in: path index map size is 8 GB, stale path metadata refreshes after 1 hour, Tantivy reads up to 2 MB per file, warms up to 4 GB per content zone, and caps each workspace content sidecar at 16 GB.

Workspace roots are dynamic: the server indexes client-provided workspaceFolders, roots, rootUri, or clientInfo.workspaceRoot; if none are provided, it falls back only to the process current directory when that directory looks like a workspace root. Relative tool paths resolve against the active indexed workspace, so clients should send the workspace for each chat session.

Index storage locations

The server keeps one index per canonical workspace root.

• Windows default: %LOCALAPPDATA%\codebase-mcp\index-v2\<workspace_hash>\
• Linux/macOS default: $XDG_CACHE_HOME/codebase-mcp/index-v2/<workspace_hash>/ or ~/.cache/codebase-mcp/index-v2/<workspace_hash>/
• Custom root: <CODEBASE_MCP_INDEX_DIR>\index-v2\<workspace_hash>\
• Tantivy sidecar: <workspace_index_dir>\tantivy-content\

LMDB stores path metadata. Tantivy is used as an optional sidecar for warmed content zones. When a query or scope cannot be served from the content index, tools fall back to filesystem scanning where appropriate.

---

Behavior and Safety

• The server exposes tools only: no MCP resources, prompts, or templates.
• Tool responses are returned in the standard MCP content array shape.
• batch_tool_call executes calls sequentially and rejects recursive batch calls.
• Mutating tools return structured write metadata for auditing; write tools return structured success or error payloads instead of free-form text.
• read_file_range and search-oriented tools keep output bounded for agent context.
• Tool calls default to a 60-second timeout. Clients may request longer calls with timeout_seconds, capped at 600 seconds.
• A global rate limiter protects the server from excessive request volume.
• server_health reports uptime and indexing status for readiness checks.

---

Large Repository Tips

• Scope paths to the smallest relevant subtree.
• Prefer concrete path tokens and basenames for fuzzy_find.
• Keep project_map shallow, for example max_depth <= 2.
• Use recursive glob excludes such as third_party/**, node_modules/**, target/**, dist/**, and out/**.
• Use read_snippets after search results instead of reading full files.
• Treat Tree-sitter results as local syntactic intelligence, not as a replacement for full semantic language servers.

---

Development

Format, lint, and test:

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test --release

Repository layout

src/
  main.rs              MCP stdio server, JSON-RPC handling, logging, timeouts
  mcp.rs               JSON-RPC request/response types
  common.rs            shared path and environment helpers
  version.rs           package version export
  indexer/             LMDB/Tantivy workspace indexing
  history/             write-change metadata support
  security/            path guarding and rate limiting
  tools/               MCP tool implementations and schemas
tests/                 integration and behavior tests

---

Project Status

• Package: codebase-mcp
• Version: 1.3.1
• Runtime: Rust + Tokio
• Transport: MCP stdio
• MCP protocol version: 2024-11-05
• Tool count: 25
• License: Apache-2.0

---

Acknowledgements

Built on Tree-sitter, Tantivy, LMDB (via heed), Tokio, and the Model Context Protocol.

License

Apache-2.0. See LICENSE.