How to Leverage MCP Tools for Codebase Analysis with codebase-memory-mcp

Install the static binary, index your repository once, and query the knowledge graph locally using 15 built-in MCP tools for instant architectural insights without external APIs.

The codebase-memory-mcp repository implements a fast, zero-dependency knowledge-graph engine that transforms your entire source tree into a structured graph. By exposing functionality through the Model-Check-Protocol (MCP), this tool allows development agents like Claude Code and Codex to perform complex structural analysis locally. No external APIs or credentials are required—just a single binary that runs entirely on your machine.

Understanding the MCP Architecture

The engine processes your codebase through several specialized layers before exposing read-only JSON-RPC endpoints to agents.

Core Components

• Tree-sitter front-end — Parses 158 languages into nodes (File, Class, Function) and basic edges (IMPORTS, CALLS). Source files: src/discover/, src/pipeline/
• Hybrid LSP layer — Resolves types, imports, inheritance, and generics to upgrade CALLS edges to fully resolved calls. Source files: src/pipeline/ (language-specific modules)
• In-memory SQLite store — Holds the graph with LZ4 compression during analysis, then persists to graph.db.zst. Source files: src/store/
• MCP server — Exposes 15 JSON-RPC tools including search_graph, trace_path, and get_architecture. Source files: src/mcp/
• Background watcher — Detects git changes and incrementally re-indexes affected files. Source files: src/watcher/

All MCP tools are read-only from the agent's perspective, ensuring no accidental mutations or secret exfiltration. The system runs as a single static binary (codebase-memory-mcp) that agents invoke directly via JSON-RPC.

Installation and Agent Configuration

Install the binary using the official installer, which automatically detects and configures compatible agents.

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

For the optional web UI, append the --ui flag:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui

The installer auto-detects Claude Code, Codex CLI, VS Code Copilot, and other supported agents, writing the necessary MCP configuration entries. Manual intervention is only required if you need custom cache paths or specific tool restrictions.

Indexing Your Repository

Before using MCP tools for codebase analysis, you must build the initial knowledge graph. Run the index_repository tool once per project:

codebase-memory-mcp cli index_repository '{"repo_path":"/absolute/path/to/your/project"}'

The indexer stores data under ~/.cache/codebase-memory-mcp/ (override with CBM_CACHE_DIR). Subsequent modifications trigger the background watcher for incremental updates, keeping the graph synchronized with your working tree.

Essential MCP Tools for Codebase Analysis

The MCP server exposes 15 specialized tools. These five provide the most immediate value for architectural analysis:

• search_graph — Structured search by label, name regex, file pattern, or degree filters.
• trace_path — BFS traversal of call graphs (inbound, outbound, or bidirectional).
• detect_changes — Maps git diff to affected symbols and classifies risk levels.
• get_architecture — Returns high-level overviews including languages, packages, routes, and hotspots.
• query_graph — Executes OpenCypher-like read-only queries for custom analytics.

When using an agent, you ask natural-language questions ("What functions call processOrder?"), and the agent translates these into precise MCP tool calls. All queries execute locally in under 1 ms.

Practical Implementation Examples

Indexing and Enabling Auto-Watch

Index your project and enable automatic re-indexing for future development sessions:

# Initial index

codebase-memory-mcp cli index_repository '{"repo_path":"/path/to/project"}'

# Enable background watching

codebase-memory-mcp config set auto_index true

Detecting Dead Code

Identify functions with no incoming CALLS edges using a Cypher-like query:

codebase-memory-mcp cli query_graph '{
  "project":"myproj",
  "query":"MATCH (f:Function) WHERE NOT EXISTS { (f)<-[:CALLS]-() } RETURN f.qualified_name"
}'

Analyzing Git Impact and Risk

Determine the downstream impact of recent commits:

codebase-memory-mcp cli detect_changes '{"project":"myproj","git_ref":"HEAD"}'

This returns changed symbols, their dependency chains, and risk ratings (high/medium/low).

Executing Custom Queries from Python

Integrate analysis into existing Python tooling by shelling out to the CLI:

import subprocess, json

def cbm_query(project, cypher):
    result = subprocess.check_output([
        "codebase-memory-mcp", "cli", "query_graph",
        json.dumps({"project": project, "query": cypher})
    ])
    return json.loads(result)

print(cbm_query("myproj", "MATCH (c:Class)-[:CALLS]->(m:Method) RETURN c.name, count(m) AS methods"))

Visualizing Architecture

Launch the web UI to explore the graph in 3D:

codebase-memory-mcp --ui=true --port=9749 &

# Navigate to http://localhost:9749

Key Source Files for Customization

Extend or debug the system by examining these critical paths:

Path	Purpose
src/main.c	Entry point launching the MCP server, CLI dispatcher, and installer
src/mcp/	JSON-RPC tool implementations (indexing, search, trace)
src/pipeline/	Multi-pass indexing: AST extraction, Hybrid LSP resolution, graph construction
src/store/	SQLite wrapper for graph persistence and LZ4 compression
src/watcher/	Background file-watcher for incremental re-indexing
scripts/install.sh	One-line installer with agent auto-detection
docs/CONFIGURATION.md	Environment variables and per-project .codebase-memory.json specification
docs/cbmignore.md	Git-style exclusion patterns for indexing

Summary

• codebase-memory-mcp converts source code into a queryable knowledge graph using Tree-sitter and Hybrid LSP analysis.
• Install via scripts/install.sh to get automatic agent configuration and optional UI support.
• Index repositories once using index_repository, then rely on background watchers for incremental updates.
• Leverage 15 MCP tools including trace_path, query_graph, and detect_changes for zero-latency local analysis.
• All data persists under ~/.cache/codebase-memory-mcp/ with no external API dependencies.

Frequently Asked Questions

What programming languages does codebase-memory-mcp support?

The Tree-sitter front-end supports 158 languages out of the box, while the Hybrid LSP layer provides enhanced type resolution for popular languages including TypeScript, Python, Rust, Go, and Java. New languages are added by extending the modules in src/pipeline/.

How does codebase-memory-mcp handle incremental updates?

The background watcher in src/watcher/ monitors git state and file system events. When changes are detected, it triggers incremental re-indexing of only affected files, updating the SQLite store in src/store/ without requiring a full rebuild.

Can I use codebase-memory-mcp without a coding assistant?

Yes. While designed for MCP integration with agents like Claude Code, the binary exposes a complete CLI interface. You can invoke any tool directly using codebase-memory-mcp cli <tool_name> followed by a JSON payload, as shown in the dead code detection example above.

Where is the graph data stored and how large is it?

Indices are stored under ~/.cache/codebase-memory-mcp/ using LZ4-compressed SQLite databases (.zst files). Typical compression ratios reduce storage to roughly 10-20% of the original source size, though this varies by language and dependency density. Set CBM_CACHE_DIR to relocate the storage path.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}