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

> Analyze your codebase with MCP tools at DeusData/codebase-memory-mcp. Install, index, and query locally for instant architectural insights. No external APIs needed.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-15

---

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

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

```

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

```bash
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:

```bash
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:

```bash

# 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:

```bash
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:

```bash
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:

```python
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:

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/install.sh) | One-line installer with agent auto-detection |
| [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md) | Environment variables and per-project [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) specification |
| [`docs/cbmignore.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.