Give your AI assistant a deep understanding of your codebase — without burning your context window.
An MCP server that parses your entire codebase with tree-sitter, builds a semantic graph of symbols, references, and dependencies, and lets AI assistants query it in real time. 18 tools, 8 languages, zero infrastructure.
Works with Claude Code, Cursor, VS Code, and any MCP-compatible client.
AI coding assistants are limited by what fits in their context window. When they need to understand your codebase — find callers of a function, trace a dependency chain, or assess the impact of a change — they resort to grep and guesswork, burning thousands of tokens on raw file reads.
mcp-codebase-intelligence gives them structured understanding in ~200 tokens instead of 50,000.
| Without | With codebase-intelligence | |
|---|---|---|
| Understand a PR | Read 1200 lines, open 23 files | semantic_diff → 8 risk flags in 3 seconds |
| Find payment logic | grep "payment" → 200 results |
search_codebase "payment processing" → 3 exact matches with docstrings |
| Impact of a change | Manually trace callers for 30 min | analyze_change_impact → 12 dependents across 6 files, instantly |
| Onboard to new repo | Read code for 2 days | architecture_diagram + query_codebase → 10 minutes |
| AI context cost | Feed 50k tokens of raw files | Structured 200-token summaries |
No Docker. No cloud. No API keys. No embeddings. Just npx.
# Add to Claude Code via npx — auto-detects your project from cwd
claude mcp add codebase-intelligence npx mcp-codebase-intelligenceOr with an explicit project path:
claude mcp add codebase-intelligence \
npx mcp-codebase-intelligence \
-e PROJECT_ROOT=/path/to/your/projectAdd to your MCP config file:
{
"mcpServers": {
"codebase-intelligence": {
"command": "npx",
"args": ["mcp-codebase-intelligence"],
"env": {
"PROJECT_ROOT": "/path/to/your/project"
}
}
}
}git clone https://github.com/g-tiwari/mcp-codebase-intelligence.git
cd mcp-codebase-intelligence
npm install && npm run build
claude mcp add codebase-intelligence \
node /path/to/mcp-codebase-intelligence/dist/index.js \
-e PROJECT_ROOT=/path/to/your/projectThat's it. The server indexes your codebase on startup and watches for changes.
Work across multiple repos, monorepos, or a mix of both — from a single MCP server.
When no config is set, the server auto-detects your project:
- Finds the git root from your current directory
- Detects monorepo markers (pnpm, lerna, nx, npm/yarn workspaces, go.work, Cargo workspace)
- Indexes accordingly
Use PROJECT_ROOTS for projects spanning multiple repositories:
claude mcp add codebase-intelligence \
npx mcp-codebase-intelligence \
-e PROJECT_ROOTS="/code/shared-models,/code/api-gateway,/code/android-app"Create .codegraph.json in your project root (or ~/.codegraph/config.json for user-level config):
{
"projects": {
"tv-backend": {
"root": "/code/monorepo",
"include": ["packages/api-gateway", "packages/shared-models"],
"roots": ["/code/android-app", "/code/webos-app"]
},
"music-service": {
"roots": ["/code/music-api", "/code/music-models"]
}
}
}Then use list_projects and switch_project tools to navigate between projects.
| Tool | What it does |
|---|---|
find_symbol |
Search for functions, classes, interfaces, types by name. Fuzzy matching, kind/scope filters. Returns signatures and docstrings. |
get_references |
Find all callers/users of a symbol. Transitive: follow the chain N levels deep. |
get_exports |
Public API surface of any file — all exported symbols with signatures. |
get_dependencies |
Import graph for a file. Transitive: see the full dependency tree. |
get_call_graph |
Who calls this function? What does it call? Tree or mermaid diagram output. |
| Tool | What it does |
|---|---|
goto_definition |
Jump to the definition of any symbol at a given position (TS/JS). |
get_type_info |
Get the inferred type of any expression at a given position (TS/JS). |
find_implementations |
Find all implementations of an interface or abstract method (TS/JS). |
| Tool | What it does |
|---|---|
semantic_diff |
Feed it a git_ref (e.g. HEAD~1). It identifies affected symbols, finds all downstream dependents, and flags breaking changes. |
analyze_change_impact |
Point it at specific lines in a file. It tells you which symbols are affected and who depends on them. |
| Tool | What it does |
|---|---|
architecture_diagram |
Auto-generate a mermaid diagram of module dependencies, grouped by directory. |
query_codebase |
Ask natural language questions: "find all API endpoints", "what does the orders module do?", "what depends on the database layer?" |
search_codebase |
Search symbols by their docstring/comment content. Find code by what it does, not what it's named. |
| Tool | What it does |
|---|---|
list_projects |
Show all configured projects, their roots, and index stats. |
switch_project |
Change active project context. All tools operate against the selected project. |
add_project |
Add a new project at runtime. Indexes immediately and persists to config. |
| Tool | What it does |
|---|---|
get_index_stats |
How many files, symbols, references, and imports are indexed. |
reindex |
Trigger a full re-index after major changes. |
| Language | Extensions | Parser |
|---|---|---|
| TypeScript | .ts .tsx .mts .cts |
tree-sitter + LSP |
| JavaScript | .js .jsx .mjs .cjs |
tree-sitter + LSP |
| Python | .py .pyi |
tree-sitter |
| Go | .go |
tree-sitter |
| Rust | .rs |
tree-sitter |
| Java | .java |
tree-sitter |
| C | .c .h |
tree-sitter |
| C++ | .cpp .cc .cxx .hpp .hxx .hh |
tree-sitter |
All languages get symbol extraction, reference tracking, import/export analysis, call graphs, and docstring/comment extraction. TypeScript/JavaScript additionally get LSP-powered go-to-definition, type info, and find-implementations.
Source Files ──> tree-sitter AST ──> Symbol Extraction ──> SQLite Graph
│
File Watcher ─────────────┤ (incremental updates)
│
MCP Tools ◄───────────────┘ (AI queries)
│
LSP Servers ──> Type Info (TS/JS)
- Parse — tree-sitter builds ASTs for all supported files
- Extract — language plugins walk the AST to find symbols, references, imports, inheritance, and docstrings
- Store — everything goes into a SQLite database with WAL mode, prepared statements, batch transactions
- Watch — chokidar monitors the filesystem; changed files are re-indexed incrementally
- Query — MCP tools run recursive SQL queries against the graph (transitive references, dependency chains)
- LSP — typescript-language-server provides type-aware intelligence for TS/JS
- Batch indexing with single-transaction writes
- Prepared statement cache -- 14 SQL statements prepared once at startup
- In-memory hash cache -- skip DB lookups for unchanged files
- Incremental updates -- only re-index files that actually changed
Tested on real-world projects: Zod, Express, gin, ripgrep, gson.
npm test146 tests across 10 test suites covering all 8 language parsers, docstring extraction, grammar regression tests, the graph engine, and semantic diff.
| Variable | Description | Default |
|---|---|---|
PROJECT_ROOT |
Path to a single codebase to index | git root of cwd() |
PROJECT_ROOTS |
Comma-separated paths for multi-repo projects | — |
DB_PATH |
Path to SQLite database file | ~/.codegraph/graphs/<project>.db |
LOG_LEVEL |
Logging verbosity: debug, info, warn, error | info |
| File | Scope | Purpose |
|---|---|---|
.codegraph.json |
Project (check into git) | Define project roots, monorepo scoping |
~/.codegraph/config.json |
User | Personal multi-project setup |
MIT