Roam Research MCP 服务器

一个提供对 Roam Research API 功能全面访问的模型上下文协议（MCP）服务器。该服务器使像 Claude 这样的 AI 助手能够通过标准化接口与您的 Roam Research 图谱进行交互。（这是一个进行中的个人项目，未得到 Roam Research 的官方认可）

安装

您可以全局安装该包：

npm install -g roam-research-mcp

或者克隆仓库并从源码构建：

git clone https://github.com/2b3pro/roam-research-mcp.git
cd roam-research-mcp
npm install
npm run build

测试

构建后运行 MCP Inspector…

npx @modelcontextprotocol/inspector node build/index.js

功能

该服务器提供了与 Roam Research 交互的强大工具：

支持 .env 文件的环境变量处理
全面的输入验证
不区分大小写的页面标题匹配
递归块引用解析
Markdown 解析与转换
每日页面集成
详细的调试日志
高效的批量操作
分层大纲创建

roam_fetch_page_by_title：通过标题获取并读取页面内容，递归解析块引用，最多4层深度
roam_create_page：创建带有可选内容的新页面
roam_create_block：在页面中创建新块（默认为当天的每日页面）
roam_import_markdown：在特定块下导入嵌套的 Markdown 内容
roam_add_todo：使用复选框语法在当天的每日页面中添加多个待办事项
roam_create_outline：创建具有适当嵌套和结构的分层大纲
roam_search_block_refs：在页面内或整个图谱中搜索块引用
roam_search_hierarchy：导航和搜索块的父子关系
roam_find_pages_modified_today：查找自今天午夜以来修改过的所有页面
roam_search_by_text：在所有页面或特定页面中搜索包含特定文本的块
roam_update_block：使用直接文本或基于模式的转换更新块内容
roam_search_by_date：根据创建或修改日期搜索块和页面
roam_search_for_tag：搜索包含特定标签的块，并可选择按附近标签进行过滤
roam_remember：存储和分类记忆或信息，并自动添加标签
roam_recall：回忆标记为 MEMORIES_TAG 的块的记忆（见下文）或同名页面上的块
roam_datomic_query：在 Roam 图谱上执行自定义 Datalog 查询以进行高级数据检索和分析

设置

创建 Roam Research API 令牌：
- 进入您的图谱设置
- 导航到“API 令牌”部分（设置 > “图谱”标签 > “API 令牌”部分，然后点击“+ 新建 API 令牌”按钮）
- 创建一个新令牌
配置环境变量：您有两种配置所需环境变量的选项：

选项 1：使用 .env 文件（推荐用于开发）在 roam-research 目录中创建一个 .env 文件：
```
ROAM_API_TOKEN=your-api-token
ROAM_GRAPH_NAME=your-graph-name
MEMORIES_TAG='#[[LLM/Memories]]'
```
选项 2：使用 MCP 设置（替代方法）将配置添加到您的 MCP 设置文件中：
- 对于 Cline (~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json)：
- 对于 Claude 桌面应用 (~/Library/Application Support/Claude/claude_desktop_config.json)：
```
{
  "mcpServers": {
    "roam-research": {
      "command": "node",
      "args": ["/path/to/roam-research-mcp/build/index.js"],
      "env": {
        "ROAM_API_TOKEN": "your-api-token",
        "ROAM_GRAPH_NAME": "your-graph-name",
        "MEMORIES_TAG": "#[[LLM/Memories]]"
      }
    }
  }
}
```
注意：服务器将首先尝试从 .env 文件加载，然后回退到 MCP 设置中的环境变量。
构建服务器（确保您在 MCP 的根目录中）：
```
cd roam-research-mcp
npm install
npm run build
```

使用

按标题获取页面

获取并读取页面内容，并解析块引用：

use_mcp_tool roam-research roam_fetch_page_by_title {
  "title": "示例页面"
}

返回页面内容的 Markdown 格式，包括：

完整的分层结构
递归解析的块引用（最多4层深度）
嵌套级别的适当缩进
完整的 Markdown 格式化

创建页面

创建带有可选内容的新页面：

use_mcp_tool roam-research roam_create_page {
  "title": "新页面",
  "content": "页面的初始内容"
}

成功时返回创建的页面的 UID。

创建块

在页面中添加新块（如果未提供 page_uid 或 title，则默认为当天的每日页面）：

use_mcp_tool roam-research roam_create_block {
  "content": "块内容",
  "page_uid": "可选目标页面 UID",
  "title": "可选目标页面标题"
}

您可以指定以下之一：

page_uid：目标页面的直接引用
title：目标页面的名称（如果不存在则创建）
都不指定：块将添加到当天的每日页面

{
  "success": true,
  "block_uid": "创建的块 UID",
  "parent_uid": "父页面 UID"
}

创建大纲

创建具有适当嵌套和结构的分层大纲：

use_mcp_tool roam-research roam_create_outline {
  "outline": [
    {
      "text": "I. 顶级",
      "level": 1
    },
    {
      "text": "A. 第二级",
      "level": 2
    },
    {
      "text": "1. 第三级",
      "level": 3
    }
  ],
  "page_title_uid": "可选目标页面",
  "block_text_uid": "可选标题文本"
}

功能：

创建复杂的大纲，最多10层嵌套
验证大纲结构和内容
维护适当的父子关系
大纲的可选标题块
如果未指定页面，则默认为当天的每日页面
创建块的高效批量操作

参数：

outline：大纲项的数组，每个项包含：
- text：大纲项的内容（必填）
- level：嵌套级别（1-10，必填）
page_title_uid：目标页面的标题或 UID（可选，默认为当天的页面）
block_text_uid：大纲的标题文本（可选）

{
  "success": true,
  "page_uid": "目标页面 UID",
  "parent_uid": "标题块 UID",
  "created_uids": ["uid1", "uid2", ...]
}

添加待办事项

在当天的每日页面中添加一个或多个待办事项：

use_mcp_tool roam-research roam_add_todo {
  "todos": [
    "第一个待办事项",
    "第二个待办事项",
    "第三个待办事项"
  ]
}

功能：

使用 Roam 复选框语法添加待办事项（{{TODO}} 待办事项文本）
支持在单个操作中添加多个待办事项
当添加超过10个待办事项时使用批量操作以提高效率
如果当天的页面不存在，则自动创建
将待办事项按顺序添加为顶级块

导入嵌套 Markdown

在特定块下导入嵌套的 Markdown 内容：

use_mcp_tool roam-research roam_import_markdown {
  "content": "- 项目 1\n  - 子项目 A\n  - 子项目 B\n- 项目 2",
  "page_uid": "可选页面 UID",
  "page_title": "可选页面标题",
  "parent_uid": "可选父块 UID",
  "parent_string": "可选精确块内容",
  "order": "first"
}

功能：

在特定块下导入内容：
- 通过 UID 或精确字符串匹配找到父块
- 通过标题或 UID 定位特定页面中的块
- 如果未指定页面，则默认为当天的页面
控制内容放置：
- 作为父块的第一个或最后一个子项添加
- 保留分层结构
- 嵌套内容的高效批量操作

全面的返回值：

{
  "success": true,
  "page_uid": "目标页面 UID",
  "parent_uid": "父块 UID",
  "created_uids": ["uid1", "uid2", ...]
}

参数：

content：要导入的嵌套 Markdown 内容
page_uid：包含父块的页面的 UID
page_title：包含父块的页面的标题（如果提供了 page_uid，则忽略）
parent_uid：要添加内容的父块的 UID
parent_string：父块的精确字符串内容（必须提供 page_uid 或 page_title）
order：添加内容的位置（“first”或“last”，默认为“first”）

搜索块引用

在页面内或整个图谱中搜索块引用：

use_mcp_tool roam-research roam_search_block_refs {
  "block_uid": "可选块 UID",
  "page_title_uid": "可选页面标题或 UID"
}

功能：

查找特定块的所有引用
搜索页面内的任何块引用
在整个图谱中搜索
支持直接和间接引用
包括块内容和位置上下文

参数：

block_uid：要查找引用的块的 UID（可选）
page_title_uid：要搜索的页面的标题或 UID（可选）

{
  "success": true,
  "matches": [
    {
      "block_uid": "引用的块 UID",
      "content": "包含 ((reference)) 的块内容",
      "page_title": "包含引用的页面"
    }
  ],
  "message": "找到 N 个块引用..."
}

按文本搜索

在所有页面或特定页面中搜索包含特定文本的块：

use_mcp_tool roam-research roam_search_by_text {
  "text": "搜索文本",
  "page_title_uid": "可选页面标题或 UID",
  "case_sensitive": true
}

功能：

在图谱中搜索任何文本
可选的页面范围搜索
区分大小写或不区分大小写的搜索
返回带有页面上下文的块内容
使用 Datalog 查询进行高效的文本匹配

参数：

text：要搜索的文本（必填）
page_title_uid：要搜索的页面的标题或 UID（可选）
case_sensitive：是否执行区分大小写的搜索（可选，默认：true 以匹配 Roam 的原生行为）

{
  "success": true,
  "matches": [
    {
      "block_uid": "匹配的块 UID",
      "content": "包含搜索文本的块内容",
      "page_title": "包含块的页面"
    }
  ],
  "message": "找到 N 个块包含 \"搜索文本\""
}

更新块内容

使用直接文本替换或基于模式的转换更新块内容：

use_mcp_tool roam-research roam_update_block {
  "block_uid": "目标块 UID",
  "content": "新的块内容"
}

或使用基于模式的转换：

use_mcp_tool roam-research roam_update_block {
  "block_uid": "目标块 UID",
  "transform_pattern": {
    "find": "\\bPython\\b",
    "replace": "[[Python]]",
    "global": true
  }
}

功能：

两种更新模式：
- 直接内容替换
- 使用正则表达式的基于模式的转换
更新前验证块是否存在
在响应中返回更新后的内容
支持全局或单次匹配替换
保留块关系和元数据

参数：

block_uid：要更新的块的 UID（必填）
content：块的新内容（如果使用直接替换）
transform_pattern：转换现有内容的模式：
- find：要查找的文本或正则表达式模式
- replace：替换的文本
- global：是否替换所有匹配项（默认：true）

{
  "success": true,
  "content": "更新后的块内容"
}

搜索标签

搜索包含特定标签的块，并可选择按附近标签进行过滤：

use_mcp_tool roam-research roam_search_for_tag {
  "primary_tag": "项目/任务",
  "page_title_uid": "可选页面标题或 UID",
  "near_tag": "可选次要标签",
  "case_sensitive": true
}

功能：

搜索包含特定标签的块
可选择按另一个标签的存在进行过滤
页面范围或全局搜索
区分大小写或不区分大小写的搜索
返回带有页面上下文的块内容
使用 Datalog 查询进行高效的标签匹配

参数：

primary_tag：要搜索的主要标签（必填）
page_title_uid：要搜索的页面的标题或 UID（可选）
near_tag：用于过滤结果的另一个标签（可选）
case_sensitive：是否执行区分大小写的搜索（可选，默认：true 以匹配 Roam 的原生行为）

{
  "success": true,
  "matches": [
    {
      "block_uid": "匹配的块 UID",
      "content": "包含 #[[primary_tag]] 的块内容",
      "page_title": "包含块的页面"
    }
  ],
  "message": "找到 N 个块引用 \"primary_tag\""
}

记住信息

存储记忆或重要信息，并自动添加标签和分类：

use_mcp_tool roam-research roam_remember {
  "memory": "要记住的重要信息",
  "categories": ["工作", "项目/Alpha"]
}

功能：

使用 #[[LLM/Memories]] 标签存储信息
添加可选的类别标签以进行组织
自动添加到当天的每日页面
支持每个记忆的多个类别
使用 roam_search_for_tag 轻松检索
保持记忆的时间顺序

参数：

memory：要记住的信息（必填）
categories：用于标记记忆的可选类别数组

{
  "success": true,
  "block_uid": "创建的块 UID",
  "content": "带有标签的记忆内容"
}

按日期搜索

根据创建或修改日期搜索块和页面：

use_mcp_tool roam-research roam_search_by_date {
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "type": "modified",
  "scope": "blocks",
  "include_content": true
}

功能：

按创建日期、修改日期或两者搜索
过滤块、页面或两者
可选日期范围，包含开始和结束日期
在结果中包含或排除块/页面内容
按时间戳排序结果
使用 Datalog 查询进行高效的基于日期的过滤

参数：

start_date：开始日期，ISO 格式（YYYY-MM-DD）（必填）
end_date：结束日期，ISO 格式（YYYY-MM-DD）（可选）
type：按“created”、“modified”或“both”搜索（必填）
scope：搜索“blocks”、“pages”或“both”（必填）
include_content：是否包含匹配块/页面的内容（可选，默认：true）

{
  "success": true,
  "matches": [
    {
      "uid": "block-or-page-uid",
      "type": "block",
      "time": 1704067200000,
      "content": "Block or page content",
      "page_title": "Page title (for blocks)"
    }
  ],
  "message": "找到 N 个匹配项，符合给定的日期范围和条件"
}

查找今日修改的页面

查找自今日凌晨以来修改过的所有页面：

use_mcp_tool roam-research roam_find_pages_modified_today {}

功能：

追踪自午夜以来对页面进行的所有修改
检测块层次结构中任何级别的更改
返回修改过的页面标题的唯一列表
包含已修改页面的数量
无需参数

{
  "success": true,
  "pages": ["Page 1", "Page 2"],
  "message": "今日找到 2 个已修改的页面"
}

执行 Datomic 查询

在您的 Roam 图表上执行自定义 Datalog 查询，以进行高级数据检索和分析：

use_mcp_tool roam-research roam_datomic_query {
  "query": "[:find (count ?p)\n :where [?p :node/title]]",
  "inputs": []
}

功能：

直接访问 Roam 的查询引擎
支持所有 Datalog 查询功能：
- 复杂的模式匹配
- 聚合函数 (count、sum、max、min、avg、distinct)
- 字符串操作 (includes?、starts-with?、ends-with?)
- 逻辑运算 (<、>、<=、>=、=、not=)
- 用于递归查询的规则
区分大小写和不区分大小写的搜索功能
对整个图进行高效查询

参数：

query：要执行的Datalog查询（必填）
inputs：查询的可选输入参数数组

{
  "success": true,
  "matches": [
    {
      "content": "[结果数据]",
      "block_uid": "",
      "page_title": ""
    }
  ],
  "message": "查询执行成功。找到N个结果。"
}

示例查询：

统计所有页面：

[:find (count ?p)
 :where [?p :node/title]]

不区分大小写的文本搜索：

[:find ?string ?title
 :where
 [?b :block/string ?string]
 [(clojure.string/lower-case ?string) ?lower]
 [(clojure.string/includes? ?lower "搜索词")]
 [?b :block/page ?p]
 [?p :node/title ?title]]

查找修改日期在某个日期之后的区块：

[:find ?block_ref ?string
 :in $ ?start_of_day
 :where
 [?b :edit/time ?time]
 [(> ?time ?start_of_day)]
 [?b :block/uid ?block_ref]
 [?b :block/string ?string]]

更多查询示例和语法文档，请参见Roam_Research_Datalog_Cheatsheet.md。

搜索区块层级

导航和搜索区块父子关系：

use_mcp_tool roam-research roam_search_hierarchy {
  "parent_uid": "可选父区块UID",
  "child_uid": "可选子区块UID",
  "page_title_uid": "可选页面标题或UID",
  "max_depth": 3
}

功能：

向上或向下搜索区块层级
查找特定区块的子区块
查找特定区块的父区块
配置搜索深度（1-10层）
可选页面范围过滤
包含每个结果的深度信息

参数：

parent_uid：查找子块的块的UID（向下搜索时必填）
child_uid：查找父块的块的UID（向上搜索时必填）
page_title_uid：要搜索的页面的标题或UID（可选）
max_depth：搜索的深度级别（可选，默认值：1，最大值：10）

{
  "success": true,
  "matches": [
    {
      "block_uid": "related-block-uid",
      "content": "块内容",
      "depth": 2,
      "page_title": "包含块的页面"
    }
  ],
  "message": "找到N个块作为子块/父块..."
}

错误处理

服务器针对常见场景提供了全面的错误处理：

配置错误：
- 缺少API令牌或图名称
- 无效的环境变量
API错误：
- 身份验证失败
- 无效请求
- 操作失败
工具特定错误：
- 页面未找到（不区分大小写的搜索）
- 通过字符串匹配未找到块
- 无效的Markdown格式
- 缺少必需的参数
- 无效的大纲结构或内容

每个错误响应都包含：

标准MCP错误代码
详细的错误消息
适用的解决建议

开发

构建

要构建服务器：

npm install
npm run build

这将：

安装所有必需的依赖项
将TypeScript编译为JavaScript
使输出文件可执行

您也可以在开发过程中使用npm run watch，以便在文件更改时自动重新编译。

使用 MCP Inspector 进行测试

MCP Inspector 是一款用于测试和调试 MCP 服务器的工具。要测试服务器：

# 使用 npx 检查：
npx @modelcontextprotocol/inspector node build/index.js

这将：

在检查器模式下启动服务器
提供一个交互式界面用于：
- 列出可用的工具和资源
- 使用自定义参数执行工具
- 查看工具响应和错误处理

许可证

MIT 许可证