Codebase Analyzer MCP

MCP server for codebase analysis with Gemini AI. Progressive disclosure keeps costs low — start with free structural analysis, drill into semantic details only when needed.

Install

Add to your MCP config (~/.mcp.json for Claude Code):

{
  "mcpServers": {
    "codebase-analyzer": {
      "command": "npx",
      "args": ["-y", "codebase-analyzer-mcp"],
      "env": {
        "GEMINI_API_KEY": "your_key_here"
      }
    }
  }
}

Restart Claude Code. The tools will be available immediately.

Gemini API key is optional — enables semantic analysis, pattern detection, and dataflow tracing. Without it, you still get structural analysis. Get a free key at https://aistudio.google.com/apikey

Tools

Tool	Description	Requires Gemini
analyze_repo	Full analysis with progressive disclosure	No
query_repo	Ask questions about a codebase	Optional
expand_section	Drill into specific analysis sections	No
read_files	Read source files from a cached analysis	No
find_patterns	Detect design/architecture patterns	Yes
trace_dataflow	Trace data flow through the system	Yes
get_analysis_capabilities	List supported languages and options	No

Analysis Layers

Layer	Cost	What You Get
Surface	Free	Files, languages, entry points, modules
Structural	Free	Symbols, imports, complexity (via tree-sitter)
Semantic	Gemini	Architecture insights, pattern detection

Results include expandable sections — you only pay for what you drill into.

CLI

npx codebase-analyzer-mcp analyze .                      # Standard analysis
npx codebase-analyzer-mcp analyze . -d surface            # Fast, free overview
npx codebase-analyzer-mcp analyze . -d deep -s            # Full semantic analysis
npx codebase-analyzer-mcp analyze . -o analysis.md        # Write structured markdown to file
npx codebase-analyzer-mcp analyze . -o analysis.json      # Write JSON to file
npx codebase-analyzer-mcp query . "how is auth handled?"  # Ask a question
npx codebase-analyzer-mcp patterns .                      # Find design patterns
npx codebase-analyzer-mcp dataflow . "user login"         # Trace data flow

Usage with Claude Code

Dump an analysis and reference it from your CLAUDE.md:

npx codebase-analyzer-mcp analyze . -o docs/codebase-analysis.md

Then add to your project's CLAUDE.md:

## Codebase Analysis
See [docs/codebase-analysis.md](docs/codebase-analysis.md) for full analysis.

Claude Code will read the summary (~50 lines) for context, then drill into specific module sections as needed using Read with offset/limit.

Development

git clone https://github.com/jaykaycodes/codebase-analyzer-mcp.git
cd codebase-analyzer-mcp
bun install
bun run build

For local MCP testing, create .mcp.json at repo root:

{
  "mcpServers": {
    "codebase-analyzer": {
      "command": "node",
      "args": ["dist/mcp/server.js"]
    }
  }
}

License

MIT