mcp-codebase-intelligence

Give your AI assistant a deep understanding of your codebase.

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. Works with Claude Code, Cursor, VS Code, and any MCP-compatible client.

Why?

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.

mcp-codebase-intelligence gives them structural understanding instead.

Quick Start

One-liner (no clone needed)

# Add to Claude Code via npx — auto-detects your project from cwd
claude mcp add codebase-intelligence npx mcp-codebase-intelligence

Or with an explicit project path:

claude mcp add codebase-intelligence \
  npx mcp-codebase-intelligence \
  -e PROJECT_ROOT=/path/to/your/project

JSON config (Claude Code, Cursor, VS Code)

Add to your MCP config file:

{
  "mcpServers": {
    "codebase-intelligence": {
      "command": "npx",
      "args": ["mcp-codebase-intelligence"],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

From source (for development)

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/project

That's it. The server indexes your codebase on startup and watches for changes.

Multi-Project Support

Work across multiple repos, monorepos, or a mix of both — from a single MCP server.

Auto-detection (zero config)

When no config is set, the server auto-detects your project:

1. Finds the git root from your current directory
2. Detects monorepo markers (pnpm, lerna, nx, npm/yarn workspaces, go.work, Cargo workspace)
3. Indexes accordingly

Multi-repo projects

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"

Config file (power users)

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.

17 Tools

Code Navigation

Code Intelligence (LSP-powered)

Change Analysis

Architecture & Discovery

Project Management

Admin

8 Languages

All languages get symbol extraction, reference tracking, import/export analysis, and call graphs. TypeScript/JavaScript additionally get LSP-powered go-to-definition, type info, and find-implementations.

How It Works

Source Files ──> tree-sitter AST ──> Symbol Extraction ──> SQLite Graph
                                                              │
                                    File Watcher ─────────────┤ (incremental updates)
                                                              │
                                    MCP Tools ◄───────────────┘ (AI queries)
                                        │
                                    LSP Servers ──> Type Info (TS/JS)

1. Parse -- tree-sitter builds ASTs for all supported files
2. Extract -- language plugins walk the AST to find symbols, references, imports, inheritance
3. Store -- everything goes into a SQLite database with WAL mode, prepared statements, batch transactions
4. Watch -- chokidar monitors the filesystem; changed files are re-indexed incrementally
5. Query -- MCP tools run recursive SQL queries against the graph (transitive references, dependency chains)
6. LSP -- typescript-language-server provides type-aware intelligence for TS/JS

Performance

• 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.

Testing

npm test

108 tests across 8 test suites covering all language parsers, grammar regression tests, the graph engine, and semantic diff.

Configuration

Environment Variables

Config Files

License

MIT