Roam Code MCP Server

官方

让 AI 编程代理先理解代码，再安全地修改代码。

分类: 开发工具第 16 / 438
Stars: ★ 517 非常热门
传输方式: stdio（本地进程）
运行环境: Python 3.10+
凭据: 无需凭据
许可证: Apache-2.0
最近提交: 1 天前
工具数: 17

69FMRS · C

Roam Code MCP Server 是一个基于 stdio 的本地代码智能服务器，适合让 AI 编程代理查询代码图、依赖、架构和变更风险。其优势是本地运行、无需 API 密钥、工具集丰富并提供安全门与证据机制；但它是静态分析系统，结果依赖索引质量，部分安全和框架检测仍需人工复核。

最强项 · 文档质量 17/20 最弱项 · 可靠性 10/20

可靠性

10/20

安全与权限

13/20

维护活跃度

16/20

文档质量

17/20

安装易用性

13/20

查看各项评分依据

可靠性 10/20: 清单明确声明 PyPI 包、版本、Python stdio 传输和默认工具预设；README 还描述了错误信封、部分失败处理及 CI 流程。但本次仅提供清单和 README，没有服务器实现、测试文件或实际握手证据，无法验证 MCP 初始化、工具列表与声明是否一致，也无法确认依赖和边界情况。因此按静态审查保守扣分。
安全与权限 13/20: README 声称支持本地分析、无 API 密钥、网络边界披露、MCP 出站密钥清理、模式门控和 HMAC 收据，这些设计信号较好；同时也披露了语法包首次下载及可选网络命令。但这些安全控制没有源代码或测试证据，写入工具的确认、权限范围、路径隔离和网络实现仍不可核验，因此不能接近满分。未发现提示材料中的红线风险。
维护活跃度 16/20: 项目未归档，提供 Apache-2.0 许可证、明确仓库归属、14.0.0 版本和多次版本更新说明；README 还描述 CI、发布供应链加固和少量开放 issue。这表明维护路径清晰且近期活跃。但未提供提交历史、依赖更新记录、漏洞响应政策或可核验的维护者响应证据，因此扣分。
文档质量 17/20: 文档覆盖安装、Python 版本、MCP 客户端配置、默认及完整工具集、预设、网络边界、限制、性能、CI、错误信封和多项已知测量局限，并明确指出若干功能仅为 advisory。示例较丰富且披露了 PATH、索引和版本评估限制。由于实际工具参数定义、实现行为和故障排查文件未随提示提供，且 README 内容末尾不完整，仍未给满分。
安装易用性 13/20: 安装和启动路径清晰：安装 roam-code[mcp]、初始化索引、运行 roam mcp，并提供 Claude、Cursor、VS Code 等配置示例；支持 Python 3.10+、Linux、macOS 和 Windows。扣分点包括依赖本地 PATH 中的 roam 命令、首次索引和语法包缓存、项目索引前置条件，以及没有实际连接或握手测试证据。

静态评测 · 未实际运行收录于 2026-08-14

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件连接数据库

适合谁

使用 AI 编程代理的大型本地代码库。
需要变更影响分析和安全重构的开发团队。
需要架构治理、代码健康度和审计证据的项目。
希望在无 API 密钥条件下进行本地代码分析的用户。

不适合谁

需要实时类型检查的场景；来源建议使用 LSP。
少于约 10 个文件的小型脚本。
只需要原始文本搜索的简单任务。
把污点或长尾检测结果视为完整安全保证的场景。

所需权限

需要访问本地代码库以发现、解析和分析源文件。
需要在代码库中创建本地 .roam/index.db 及相关分析状态。
使用写入、持久化或变更相关工具时，可能需要更新 .roam 控制文件、运行记录或证据文件。
默认不需要 API 密钥或云端登录。

风险与副作用

索引过时、缺失或部分完成时，分析结果可能不完整；应检查返回的状态和错误信号。
静态分析和框架惯用法检测并不等同于实时类型检查或深度 SAST；部分检测结果仅供调查。
full 预设包含 244 个工具，可能扩大代理提示词表面。
首次使用 tree-sitter-language-pack 时可能下载经校验的平台语法包；其他联网命令和网络标志需要显式启用。
写入或自动化代理模式可能产生实际文件和运行记录变更。

安装接入

准备工作

运行环境：Python 3.10+

其他可选配置项（1 个）

ROAM_MCP_PRESET 可选选择 MCP 工具预设：core（默认，17 个工具）、review、refactor、debug、architecture、compliance、compile-curated 或 full（244 个工具），无需从外部获取。

需要 Python 3.10+。先运行 pip install "roam-code[mcp]"，进入目标代码库后运行 roam init 建立 .roam/index.db，再运行 roam mcp 启动 stdio MCP 服务器。也可以在 Claude Code、Claude Desktop、Cursor 或 VS Code 的 MCP 配置中使用 command 为 roam、args 为 ["mcp"]。可通过 ROAM_MCP_PRESET 选择 core、review、refactor、debug、architecture、compliance、compile-curated 或 full。

.mcp.json

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

以 Claude Code 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

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

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add roam-code -- roam mcp

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

先运行 pip install "roam-code[mcp]" 和 roam init 建立索引，然后在客户端配置 roam mcp 后重启；工具列表中应出现 roam_understand、roam_ask 等 roam_ 前缀的工具，用 roam_understand 提问能返回代码库概况即说明连接成功。

常见排障

确认已安装 Python 3.10+，且 roam 位于 PATH 中。
确认先在目标代码库运行 roam init，并检查 .roam/index.db 是否存在。
如果服务器无法启动，直接运行 roam mcp 检查命令是否可用。
如果结果为空或不完整，检查索引是否缺失、过时或被中断，并重新建立索引。
确认客户端配置使用 command 为 roam、args 为 ["mcp"]，并为 Claude Desktop 设置正确的 cwd。
检查 ROAM_MCP_PRESET 是否选择了所需工具集。

试试这样问

连接成功后，可以直接对 AI 助手这样说：

理解一下这个代码库的整体架构和健康度
谁调用了 handleSave 这个函数？列出调用者
在我修改这个符号之前，先评估一下改动的影响范围和受影响的测试
这个代码库里有哪些死代码？

工具能力 17

roam_alerts 只读

查询代码库告警和发现。

roam_ask 只读

将自然语言代码库问题路由到图分析查询。

roam_batch_search 只读

批量执行代码库搜索。

roam_coupling 只读

分析文件或符号之间的变更耦合关系。

roam_dead_code 只读

检测可能未使用的代码。

roam_deps 只读

查询文件或符号的依赖关系。

roam_diagnose_issue 只读

对代码问题进行根因排序和诊断。

roam_fetch_handle 只读

获取此前查询返回的结果句柄。

展开其余 9 个工具

roam_file_info 只读

获取文件结构、定义和健康信息。

roam_grep 只读

执行带有代码图上下文的文本搜索。

roam_metrics 只读

查询代码库指标。

roam_prepare_change 只读

为代码变更准备影响和安全上下文。

roam_search_symbol 只读

按符号搜索代码定义。

roam_taint 只读

执行基于代码图的污点分析。

roam_understand 只读

生成代码库的整体简报，包括技术栈、架构、健康度和入口点。

roam_uses 只读

查询符号的精确引用，避免字符串匹配误报。

roam_expand_toolset 写入

扩展到其他 Roam MCP 工具预设。

使用场景

在修改符号前查询调用方、依赖关系、影响范围和受影响测试。

为 AI 编程代理提供代码库结构、上下文和架构事实。

执行死代码、污点、耦合、指标和代码搜索分析。

为代码审查、重构和 CI 安全门提供结构化证据。

支持客户端

Claude Code

Claude Desktop

Cursor

VS Code with Copilot

依据项目文档列出，未经本站实测。

详细介绍

Roam Code 是一个本地代码库智能 CLI 和 MCP 服务器。它使用 SQLite 代码图分析符号、调用、导入、架构、Git 历史、风险和测试影响，支持 28 种语言及 244 个 MCP 工具。默认 core 预设包含 17 个工具。分析在本机进行，不需要 API 密钥，并提供变更安全门、验证结果和审计证据。