Roam Research MCP

Roam Research MCP + CLI

漫游研究MCP+CLI

](https://badge.fury.io/js/roam-research-mcp)   ](https://github.com/2b3pro/roam-research-mcp/blob/main/LICENSE)

介绍

我创建这个项目是为了解决一个个人问题：我想直接从以下位置管理我的漫游研究图 克劳德代码 （及其他法学硕士）。当我建造 模型上下文协议（MCP） 服务器允许AI代理访问我的笔记，我意识到底层工具足够强大，可以独立运行。

最初作为人工智能代理的后端发展成为功能齐全的 独立CLI现在，您可以直接从终端将内容放入Roam、搜索图形和管理任务中使用同样强大的API功能，而不需要LLM。

无论你是想让Claude在你的知识库上拥有超能力，还是只是想为你自己的脚本提供一个强大的CLI，这个项目都能满足你的需求。

独立CLI： roam

这 roam CLI允许您直接从终端与图形交互。支持 标准输入（stdin）管道 适用于所有内容创建和检索命令，使其非常适合自动化工作流程。

快速示例

# Save a quick thought to your daily page
roam save "Idea: A CLI for Roam would be cool"

# Pipe content from a file to a new page
cat meeting_notes.md | roam save --title "Meeting: Project Alpha"

# Create a TODO item on today's daily page
echo "Buy milk" | roam save --todo

# Prepend to top of page (newest-first ordering)
roam save -p "Changelog" --order first "v2.18.0 release"

# Search your graph and pipe results to another tool
roam search "important" --json | jq .

# Search for pages by namespace prefix
roam search --namespace "Convention"    # Finds all Convention/* pages

# Fetch a page by title
roam get "Roam Research"

# Fetch daily pages using any date format (auto-normalized)
roam get today                          # Today's daily page
roam get 2026-03-21                     # ISO date → "March 21st, 2026"
roam get "03/21/2026"                   # US date → "March 21st, 2026"
roam get "March 21"                     # Named (assumes current year)

# Fetch a block with ancestors (parent chain to page root)
roam get abc123def -a              # Block + children + ancestors
roam get abc123def -a -d 0         # Ancestors only, no children

# Fetch page by UID or Roam URL
roam get page abc123def
roam get page "https://roamresearch.com/#/app/my-graph/page/abc123def"

# Sort and group results
roam get --tag Project --sort created --group-by tag

# Find references (backlinks) to a page
roam refs "Project Alpha"

# Update a block (e.g., toggle TODO status)
roam update ((block-uid)) --todo

# Multi-graph: read from a specific graph
roam get "Page Title" -g work

# Multi-graph: write to a protected graph
roam save "Note" -g work --write-key "$ROAM_SYSTEM_WRITE_KEY"

可用命令： get, search, save, refs, update, batch, rename, status. 跑 roam --help 有关任何命令的详细信息。

安装

npm install -g roam-research-mcp
# The 'roam' command is now available globally

______________________________________________________________________

MCP服务器工具

MCP服务器将这些工具暴露给AI助手（如Claude），使他们能够智能地读取、写入和组织您的漫游图。

多图支持： 所有工具均接受可选 graph 和 write_key 参数。使用 graph 从您的 ROAM_GRAPHS 配置，以及 write_key 用于在受保护的图上进行写操作。

______________________________________________________________________

配置

环境变量

单图模式

对于单个漫游图，请在您的环境或 .env 文件：

ROAM_API_TOKEN=your-api-token
ROAM_GRAPH_NAME=your-graph-name

多图模式（v2.0+）

从单个服务器实例连接到多个漫游图：

ROAM_GRAPHS='{
  "personal": {"token": "token-1", "graph": "personal-db", "memoriesTag": "#[[Personal Memories]]"},
  "work": {"token": "token-2", "graph": "work-db", "protected": true, "memoriesTag": "#[[Work Memories]]"},
  "research": {"token": "token-3", "graph": "research-db"}
}'
ROAM_DEFAULT_GRAPH=personal
ROAM_SYSTEM_WRITE_KEY=your-secret-key

图形配置选项：

写保护： 受保护的图形需要 write_key 参数匹配 ROAM_SYSTEM_WRITE_KEY 对于任何写入操作。这可以防止意外写入敏感图形。

*可选：*

• ROAM_MEMORIES_TAG：默认标记 roam_remember/roam_recall （根据图表回退 memoriesTag 未设置）。
• HTTP_STREAM_PORT：启用HTTP流（默认为8088）。

运行服务器

1.标准模式（默认） 最适合本地集成（例如，Claude Desktop、IDE扩展）。

npx roam-research-mcp

注意：Stdio模式不使用任何网络端口。

2.HTTP流模式 最适合远程访问或web客户端。

HTTP_STREAM_PORT=8088 npx roam-research-mcp

3.Docker

docker run -p 8088:8088 --env-file .env roam-research-mcp

在LLM中配置

克劳德桌面/克莱恩：

添加到您的MCP设置文件（例如。， ~/Library/Application Support/Claude/claude_desktop_config.json):

*单幅图：*

{
  "mcpServers": {
    "roam-research": {
      "command": "npx",
      "args": ["-y", "roam-research-mcp"],
      "env": {
        "ROAM_API_TOKEN": "your-token",
        "ROAM_GRAPH_NAME": "your-graph"
      }
    }
  }
}

*多图：*

{
  "mcpServers": {
    "roam-research": {
      "command": "npx",
      "args": ["-y", "roam-research-mcp"],
      "env": {
        "ROAM_GRAPHS": "{\"personal\":{\"token\":\"token-1\",\"graph\":\"personal-db\",\"memoriesTag\":\"#[[Memories]]\"},\"work\":{\"token\":\"token-2\",\"graph\":\"work-db\",\"protected\":true}}",
        "ROAM_DEFAULT_GRAPH": "personal",
        "ROAM_SYSTEM_WRITE_KEY": "your-secret-key"
      }
    }
  }
}

查询块解析器（v2.11.0+）

一个用于以编程方式解析和执行Roam查询块的实用程序。转换 {{[[query]]: ...}} 将语法转换为数据日志查询。

支持的条款

相对日期

这 between 子句支持相对日期： today, yesterday, last week, last month, this year, 7 days ago, 2 months ago等等。

用法

import { QueryExecutor } from 'roam-research-mcp/query';

const executor = new QueryExecutor(graph);

// Execute a query
const results = await executor.execute(
  '{{[[query]]: "My Query" {and: [[Project]] {between: [[last month]] [[today]]}}}}'
);

// Parse without executing (for debugging)
const { name, query } = QueryParser.parseWithName(queryBlock);

工具函数

import { isQueryBlock, extractQueryBlocks } from 'roam-research-mcp/query';

// Detect if text is a query block
isQueryBlock('{{[[query]]: [[tag]]}}'); // true

// Extract all query blocks from a string
extractQueryBlocks(pageContent); // ['{{[[query]]: ...}}', ...]

______________________________________________________________________

支持

如果这个项目能帮助你管理你的知识库或建立很酷的代理，考虑给我买杯咖啡！它有助于保持更新。

https://paypal.me/2b3/5

______________________________________________________________________

许可证

MIT许可证-创建者 沈.