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