← Back to directory

Roam Code MCP Server

Official

Let AI coding agents understand code before changing it safely.

GitHub source repository ↗

★ 511 Stars Category · Dev Tools Very popular Source revision 264e2eb9d19a

69FMRS · C

Reliability

10/20

Security and permissions

13/20

Maintenance

16/20

Documentation

17/20

Setup experience

13/20

Roam Code MCP Server is a stdio-based local code intelligence server for giving AI coding agents graph, dependency, architecture, and change-risk context. Its strengths are local execution, no API-key requirement, a broad tool surface, and safety and evidence mechanisms. It remains a static-analysis system whose results depend on index quality, and some security and framework detectors require human review.

Read the FMRS scoring method →

Roam Code is a local codebase intelligence CLI and MCP server. It uses a SQLite code graph to analyze symbols, calls, imports, architecture, Git history, risk, and test impact across 28 languages and 244 MCP tools. The default core preset exposes 17 tools. Analysis runs locally without API keys and includes change-safety gates, verification results, and audit evidence.

Tools

roam_alerts

Query codebase alerts and findings.

roam_ask

Route natural-language codebase questions to graph-analysis recipes.

roam_batch_search

Run searches across multiple codebase queries.

roam_coupling

Analyze change coupling between files or symbols.

roam_dead_code

Detect potentially unused code.

roam_deps

Query dependencies of files or symbols.

roam_diagnose_issue

Rank likely root causes for a code issue.

roam_fetch_handle

Retrieve results referenced by a previous query handle.

roam_file_info

Get file structure, definitions, and health information.

roam_grep

Run text search with code-graph context.

roam_metrics

Query codebase metrics.

roam_prepare_change

Prepare impact and safety context for a code change.

roam_search_symbol

Search for code definitions by symbol.

roam_taint

Run code-graph-based taint analysis.

roam_understand

Generate a codebase briefing covering stack, architecture, health, and entry points.

roam_uses

Find precise symbol references without string-match false positives.

roam_expand_toolset

Expand access to additional Roam MCP tool presets.

Setup

Python 3.10+ is required. Run pip install "roam-code[mcp]", enter the target repository, run roam init to create .roam/index.db, and then run roam mcp to start the stdio MCP server. The same server can be configured in Claude Code, Claude Desktop, Cursor, or VS Code with command roam and args ["mcp"]. Set ROAM_MCP_PRESET to choose core, review, refactor, debug, architecture, compliance, compile-curated, or full.

claude_desktop_config.json

{"mcpServers":{"roam-code":{"command":"roam","args":["mcp"]}}}

Generate and validate client config

Fit and risk

Best for

Large local repositories used with AI coding agents.
Development teams that need change-impact analysis and safer refactoring.
Projects requiring architecture governance, code health metrics, and audit evidence.
Users who want local code analysis without API keys.

Not for

Real-time type checking; the source recommends an LSP for that purpose.
Small scripts with fewer than about 10 files.
Simple tasks requiring only raw text search.
Treating taint or long-tail detector results as complete security coverage.

Required permissions

Access to the local repository is needed to discover, parse, and analyze source files.
The server creates the local .roam/index.db and related analysis state.
Write, persistence, or change-related tools may update .roam control files, run records, or evidence files.
API keys and cloud login are not required by default.

Risks and side effects

Missing, stale, or interrupted indexes can produce incomplete analysis; inspect returned status and error signals.
Static analysis and framework-idiom detection are not substitutes for real-time type checking or deep SAST; some findings are advisory.
The full preset exposes 244 tools and may enlarge an agent's prompt surface.
The first tree-sitter-language-pack use may download a checksum-verified platform grammar bundle; other network-capable commands and flags are opt-in.
Write operations or autonomous-agent modes may create real repository files and run-record changes.

Troubleshooting

Confirm Python 3.10+ is installed and that roam is available on PATH.
Run roam init in the target repository and verify that .roam/index.db exists.
If the server does not start, run roam mcp directly to check the executable and error output.
For empty or incomplete results, check whether the index is missing, stale, or interrupted, then rebuild it.
Verify that the client configuration uses command roam and args ["mcp"], and set the correct cwd for Claude Desktop.
Check ROAM_MCP_PRESET if expected tools are unavailable.

Use cases

Inspect callers, dependencies, blast radius, and affected tests before editing a symbol.

Give AI coding agents structured codebase context and architecture facts.

Run dead-code, taint, coupling, metrics, and code-search analysis.

Provide structured evidence for code review, refactoring, and CI safety gates.

Supported clients

Claude CodeFull support

Claude DesktopFull support

CursorFull support

VS Code with CopilotFull support

Related MCP servers

Compare with other MCP servers