M
MCP Directory CURATED DIRECTORY
911 MCP servers indexed
中文
← Back to directory
R

Roam Code MCP Server

Official
Let AI coding agents understand code before changing it safely.
How to install ↓ Compare GitHub source repository ↗
Category
Dev Tools #16 of 438
Stars
★ 517 Very popular
Transport
stdio (local process)
Runtime
Python 3.10+
Credentials
No credential needed
License
Apache-2.0
Last commit
Tools
17
69FMRS · C

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.

Strongest · Documentation 17/20 Weakest · Reliability 10/20

Reliability
10/20
Security and permissions
13/20
Maintenance
16/20
Documentation
17/20
Setup experience
13/20
Why each score
Reliability 10/20
The manifest specifies a PyPI package, version, Python runtime, stdio transport, and a default tool preset. The README also describes structured failure envelopes, partial-failure handling, and CI workflows. However, this review includes no server implementation, tests, or actual handshake evidence, so MCP initialization, tool-list consistency, dependency behavior, and edge cases cannot be verified. The score is therefore conservative.
Security and permissions 13/20
The README claims local analysis, no API keys, a disclosed network boundary, MCP egress secret scrubbing, mode gating, and HMAC-linked receipts; these are positive design signals. It also discloses first-use grammar downloads and optional network-capable commands. Still, the controls are not supported by source code or tests here, and write confirmation, permission scope, path isolation, and network behavior remain unverifiable. No stated red-line risk is evident.
Maintenance 16/20
The project is not archived and provides an Apache-2.0 license, an identifiable repository, version 14.0.0, and multiple recent release notes. The README also describes CI, supply-chain hardening, and only a small number of open issues, indicating an active maintenance path. There is no supplied commit history, dependency-update record, vulnerability-response policy, or verifiable maintainer-response evidence, so points are deducted.
Documentation 17/20
Documentation covers installation, Python requirements, MCP client configuration, default and full toolsets, presets, network boundaries, limitations, performance, CI, failure envelopes, and the limits of several measurements. It provides many examples and discloses PATH, indexing, and version-evaluation caveats. The actual tool schemas, implementation behavior, and troubleshooting files are not supplied, and the README excerpt is incomplete at the end, so full marks are not justified.
Setup experience 13/20
The setup path is clear: install roam-code[mcp], initialize an index, run roam mcp, and configure clients such as Claude, Cursor, and VS Code. Python 3.10+ and Linux, macOS, and Windows are stated as supported. Deductions apply because the client depends on a roam executable being on PATH, indexing and grammar-cache setup are prerequisites, and no real connection or handshake test evidence is provided.

Static review · not runListed 2026-08-14

Read the FMRS scoring method →

Fit and risk

What it can accessReads local filesConnects to a database

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.

Setup

Before you start

Runtime：Python 3.10+

Other optional settings (1)
ROAM_MCP_PRESET optional Selects the MCP tool preset: core (default, 17 tools), review, refactor, debug, architecture, compliance, compile-curated, or full (244 tools); nothing to obtain externally.

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.

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

Shown for Claude Code. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json
{
  "servers": {
    "roam-code": {
      "command": "roam",
      "args": [
        "mcp"
      ]
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal
claude mcp add roam-code -- roam mcp

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

Install with pip install "roam-code[mcp]", run roam init to build the index, then after configuring the client to run "roam mcp" and restarting, roam_-prefixed tools like roam_understand and roam_ask should appear in the client's tool list; asking roam_understand for a codebase overview confirms the connection.

Troubleshooting

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

Things to try

Once connected, you can ask your AI assistant things like:

  • Give me a briefing on this codebase's architecture and health score
  • Who calls the handleSave function? List the callers with line numbers
  • Assess the blast radius and affected tests before I edit this symbol
  • Find dead code in this repository

Tools 17

roam_alerts read-only
Query codebase alerts and findings.
roam_ask read-only
Route natural-language codebase questions to graph-analysis recipes.
roam_batch_search read-only
Run searches across multiple codebase queries.
roam_coupling read-only
Analyze change coupling between files or symbols.
roam_dead_code read-only
Detect potentially unused code.
roam_deps read-only
Query dependencies of files or symbols.
roam_diagnose_issue read-only
Rank likely root causes for a code issue.
roam_fetch_handle read-only
Retrieve results referenced by a previous query handle.
Show 9 more tools
roam_file_info read-only
Get file structure, definitions, and health information.
roam_grep read-only
Run text search with code-graph context.
roam_metrics read-only
Query codebase metrics.
roam_prepare_change read-only
Prepare impact and safety context for a code change.
roam_search_symbol read-only
Search for code definitions by symbol.
roam_taint read-only
Run code-graph-based taint analysis.
roam_understand read-only
Generate a codebase briefing covering stack, architecture, health, and entry points.
roam_uses read-only
Find precise symbol references without string-match false positives.
roam_expand_toolset writes
Expand access to additional Roam MCP tool presets.

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 Code
Claude Desktop
Cursor
VS Code with Copilot

Listed from the project's documentation, not tested by this site.

Overview

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.

Similar servers

Context7 80 · B

Upstash's official server providing up-to-date third-party library docs for AI coding assistants

★ 62.9k · Tools 2 Compare with this →
Compare with other MCP servers

Source revision f0bdb6352cee Data synced 2026-10-12 Read the FMRS scoring method