CodeAtlas MCP

CodeAtlas MCP is a local-first, enterprise-ready Code Graph RAG MCP Server. It converts a software repository into a queryable code knowledge graph, enriches it with Graph RAG, and exposes it through an MCP server so Claude Code and other AI coding agents can understand a codebase without repeatedly scanning files.

Status: Phases 1–7 implemented. The MCP server (codeatlas mcp start) exposes all 10 tools over stdio. Phase 8 adds the Java parser. See Implementation status.

MVP scope: Python and React/Node (JavaScript, TypeScript, JSX, TSX) projects. Additional languages (e.g. Java) and standalone SQL extraction are planned for future releases.

Why code-graph indexing helps AI agents

AI coding agents waste context re-reading files to answer "what calls what", "what breaks if I change this", and "which tests should run". CodeAtlas builds a structured graph once and answers these questions deterministically — with file paths, line numbers, and provenance for every relationship.

Requirements

• Python 3.11+
• SQLite (bundled with Python)

JavaScript/TypeScript parsing uses tree-sitter (installed automatically via prebuilt wheels — no Node.js runtime required). No LLM is required for indexing (spec constraint: indexing must work offline).

Install from PyPI

CodeAtlas is published to PyPI as codeatlas-mcp-server. The distribution name is codeatlas-mcp-server; the installed command and import package are both codeatlas.

pip install codeatlas-mcp-server

For MCP use, install it so the codeatlas command is on your PATH even without an activated virtualenv (MCP clients launch it as a subprocess). The cleanest way is pipx:

pipx install codeatlas-mcp-server

Verify the install:

codeatlas version

Install from source (development)

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

pip install -e ".[dev]"

Quick start

# 1. Initialize .codeatlas/, the SQLite database, and codeatlas.yaml
codeatlas init /path/to/repo

# 2. Build the index (deterministic, no LLM needed)
codeatlas index /path/to/repo

# 3. Inspect index status and row counts
codeatlas status /path/to/repo

# 4. Query the graph
codeatlas find-symbol create_order /path/to/repo
codeatlas trace-flow "POST /orders" /path/to/repo
codeatlas impact OrderService.create_order /path/to/repo
codeatlas recommend-tests /path/to/repo --changed-symbols create_order

# 5. Ask a natural-language question (Graph RAG)
codeatlas ask "Where is create_order implemented and what does it call?" /path/to/repo

# 6. Start the MCP server (for Claude Code, VS Code, Cursor, etc.)
CODEATLAS_REPO_PATH=/path/to/repo codeatlas mcp start

Graph RAG works fully offline: with no LLM configured it returns a deterministic, evidence-grounded answer built from the graph. Configuring an Ollama or Bedrock provider (and enabling indexing.generate_embeddings) adds semantic retrieval and LLM-written prose.

All commands print structured JSON on stdout. Logs go to stderr so the MCP stdio transport stays clean.

For the full command reference see docs/cli_usage.md. For connecting the MCP server to Claude Code, VS Code, and Cursor, see docs/mcp_usage.md.

Using CodeAtlas

There are two ways to use CodeAtlas: directly from the command line, or as an MCP server wired into an AI coding assistant. Both read the same .codeatlas/ index, so index once and use it either way.

Via the CLI

After pip install codeatlas-mcp-server, the codeatlas command is available. Point it at any repository (defaults to the current directory).

# 1. Initialize .codeatlas/, the SQLite database, and codeatlas.yaml
codeatlas init /path/to/repo

# 2. Build the index (deterministic, offline, no LLM required)
codeatlas index /path/to/repo

# 3. Inspect index status and row counts
codeatlas status /path/to/repo

Once indexed, query the graph:

# Locate a symbol definition and its usages
codeatlas find-symbol create_order /path/to/repo

# Trace a request flow (route → handler → service → repository → DB)
codeatlas trace-flow "POST /orders" /path/to/repo

# See what a change to a symbol would affect (callers, routes, tests)
codeatlas impact OrderService.create_order /path/to/repo

# Recommend tests for changed symbols/files
codeatlas recommend-tests /path/to/repo --changed-symbols create_order

# Ask a natural-language question (Graph RAG)
codeatlas ask "Where is create_order implemented and what does it call?" /path/to/repo

Every command prints structured JSON on stdout; logs go to stderr. Add -v/--verbose for debug logging. Run codeatlas --help (or codeatlas <command> --help) for all options, and see docs/cli_usage.md for the full reference.

Via the MCP server

CodeAtlas exposes its code graph over the Model Context Protocol on stdio, so AI agents can query it without re-scanning files. Index the repo first, then start the server:

codeatlas init  /path/to/repo
codeatlas index /path/to/repo

# Start the MCP server over stdio (normally launched by the client, see below)
CODEATLAS_REPO_PATH=/path/to/repo codeatlas mcp start

The server is configured entirely through environment variables:

Variable	Required	Purpose
CODEATLAS_REPO_PATH	✅	Absolute path to the repository to serve.
CODEATLAS_CONFIG	optional	Absolute path to codeatlas.yaml.
CODEATLAS_LLM_PROVIDER	optional	bedrock | ollama | none.
CODEATLAS_LOG_LEVEL	optional	e.g. DEBUG, INFO.

It exposes 10 tools — index_repository, explore_codebase, find_symbol, trace_flow, impact_analysis, recommend_tests, query_graph_rag, get_code_context, list_modules, and explain_symbol. All deterministic tools work offline; query_graph_rag uses your configured LLM provider if one is set, and otherwise returns structured, evidence-only results.

Asking in plain English (and the CLI equivalent)

You don't call MCP tools directly — you ask your AI assistant in plain English and it picks the right tool. Each request maps to an equivalent codeatlas command you can run yourself:

Ask your assistant…	MCP tool	CLI equivalent
"Index / re-index this repository."	index_repository	codeatlas index <repo>
"Give me an overview of this codebase."	explore_codebase	(MCP-only; see codeatlas status)
"Where is create_order defined and who calls it?"	find_symbol	codeatlas find-symbol create_order <repo>
"Trace what happens on POST /orders."	trace_flow	codeatlas trace-flow "POST /orders" <repo>
"If I change create_order, what breaks?"	impact_analysis	codeatlas impact create_order <repo>
"Which tests should I run after editing create_order?"	recommend_tests	codeatlas recommend-tests <repo> --changed-symbols create_order
"How does the checkout flow work?"	query_graph_rag	codeatlas ask "How does the checkout flow work?" <repo>
"Give me the full context for create_order."	get_code_context	(MCP-only)
"List all modules in the index."	list_modules	(MCP-only; see codeatlas status)
"Explain what create_order does."	explain_symbol	(MCP-only)

You don't need to name the tool — the assistant maps intent automatically. For the full prompt-and-argument reference see docs/mcp_usage.md.

AI IDE / client configuration

MCP clients launch codeatlas mcp start as a subprocess, so the codeatlas command must resolve on your PATH (use pipx install codeatlas-mcp-server, or point command at the absolute path to the executable). Every client uses the same three pieces: command: codeatlas, args: ["mcp", "start"], and an env block with at least CODEATLAS_REPO_PATH.

Claude Code

Option A — CLI (recommended):

claude mcp add codeatlas \
  --env CODEATLAS_REPO_PATH=/path/to/repo \
  --env CODEATLAS_CONFIG=/path/to/repo/codeatlas.yaml \
  -- codeatlas mcp start

Option B — project .mcp.json (checked in so your team shares it):

{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["mcp", "start"],
      "env": {
        "CODEATLAS_REPO_PATH": "/path/to/repo",
        "CODEATLAS_CONFIG": "/path/to/repo/codeatlas.yaml"
      }
    }
  }
}

Run /mcp inside Claude Code to confirm codeatlas is connected.

Claude Desktop

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["mcp", "start"],
      "env": {
        "CODEATLAS_REPO_PATH": "/path/to/repo",
        "CODEATLAS_CONFIG": "/path/to/repo/codeatlas.yaml"
      }
    }
  }
}

Restart Claude Desktop; the CodeAtlas tools appear in the tools (🔨) menu.

VS Code (Copilot agent mode)

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "codeatlas": {
      "type": "stdio",
      "command": "codeatlas",
      "args": ["mcp", "start"],
      "env": {
        "CODEATLAS_REPO_PATH": "${workspaceFolder}",
        "CODEATLAS_CONFIG": "${workspaceFolder}/codeatlas.yaml"
      }
    }
  }
}

${workspaceFolder} expands to the open project path, keeping the config portable. Use MCP: List Servers to start/stop and view logs.

Cursor

Add to .cursor/mcp.json (project scope) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["mcp", "start"],
      "env": {
        "CODEATLAS_REPO_PATH": "/path/to/repo",
        "CODEATLAS_CONFIG": "/path/to/repo/codeatlas.yaml"
      }
    }
  }
}

Then open Cursor Settings → MCP and confirm codeatlas shows a green "connected" indicator.

Windsurf & other MCP clients

Any stdio-capable MCP client works with the same shape. Windsurf reads ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["mcp", "start"],
      "env": { "CODEATLAS_REPO_PATH": "/path/to/repo" }
    }
  }
}

If codeatlas is not on the global PATH, point command at the absolute path instead — e.g. C:\\path\\to\\.venv\\Scripts\\codeatlas.exe on Windows (note the doubled backslashes in JSON) or /path/to/.venv/bin/codeatlas on macOS/Linux. For the full connection guide, tool reference, and LLM-provider setup, see docs/mcp_usage.md.

Configuration

codeatlas init writes a codeatlas.yaml with safe enterprise defaults (local-only, no external LLM, embeddings off). See configs/codeatlas.example.yaml for the full schema. Environment overrides:

Variable	Effect
CODEATLAS_CONFIG	Explicit config file path
CODEATLAS_REPO_PATH	Overrides repository.path
CODEATLAS_LLM_PROVIDER	Overrides llm.provider (bedrock/ollama/none)

Security model

• Local-first: no code leaves the machine unless explicitly configured.
• Default exclusions: .git, node_modules, build dirs, secrets (.env, *.pem, *.key, ...), and binaries are skipped.
• Deterministic indexing: file hashes drive incremental re-indexing.
• Secret redaction: source snippets are scrubbed of keys, tokens, connection strings, and secret-like assignments before they enter any RAG context or reach an LLM (spec §15.2).
• Provider guardrails: remote LLM/embedding providers are refused unless security.allow_external_llm is set; the default is fully local/offline.
• Audit logging arrives with Phase 8.

Running tests

pytest              # full suite
pytest tests/unit   # unit tests only

Implementation status

Phase	Scope	Status
1	Project foundation (config, logging, models, CLI)	✅
2	Storage (SQLite schema, migrations, repository APIs, FTS5)	✅
3	Scanner & indexer (scan, filter, hash, incremental, run tracking)	✅
4	Parsers & graph builder (Python via ast; JS/TS/JSX/TSX via tree-sitter)	✅
5	Graph query (find-symbol, trace-flow, impact, recommend-tests, risk)	✅
6	Graph RAG (embeddings, vector + FTS retrieval, context builder, ask)	✅
7	MCP server (stdio, 10 tools: index, explore, find-symbol, trace-flow, impact, tests, RAG, context, modules, explain)	✅
8–10	Additional languages (Java), SQL extraction, watch mode, docs/hardening	⏳

License

Apache-2.0. See LICENSE.