Roam Research MCP 服务器

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

<a href="https://glama.ai/mcp/servers/fzfznyaflu"><img width="380" height="200" src="https://glama.ai/mcp/servers/fzfznyaflu/badge" alt="Roam Research MCP server" /></a>

安装

您可以全局安装该软件包：

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

功能

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

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

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

设置

1. 创建一个 Roam Research API 令牌:

   • 转到您的图谱设置
   • 导航到“API 令牌”部分（设置 > “图谱”选项卡 > “API 令牌”部分，然后单击“+ 新建 API 令牌”按钮）
   • 创建一个新令牌

2. 配置环境变量： 您有两种配置所需环境变量的选项：

   选项 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 设置中的环境变量。

3. 构建服务器（确保您位于 MCP 的根目录中）：

   cd roam-research-mcp
   npm install
   npm run build
   

用法

按标题获取页面

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

use_mcp_tool roam-research roam_fetch_page_by_title {
  "title": "Example Page"
}

以 markdown 格式返回页面内容，包含：

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

创建页面

创建一个新页面，带有可选内容：

use_mcp_tool roam-research roam_create_page {
  "title": "New Page",
  "content": "Initial content for the page"
}

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

创建块

向页面添加一个新块（如果未提供 page_uid 或 title，则默认为今天的每日页面）：

use_mcp_tool roam-research roam_create_block {
  "content": "Block content",
  "page_uid": "optional-target-page-uid",
  "title": "optional-target-page-title"
}

您可以指定以下任一项：

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

返回：

{
  "success": true,
  "block_uid": "created-block-uid",
  "parent_uid": "parent-page-uid"
}

创建大纲

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

use_mcp_tool roam-research roam_create_outline {
  "outline": [
    {
      "text": "I. Top Level",
      "level": 1
    },
    {
      "text": "A. Second Level",
      "level": 2
    },
    {
      "text": "1. Third Level",
      "level": 3
    }
  ],
  "page_title_uid": "optional-target-page",
  "block_text_uid": "optional-header-text"
}

功能：

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

参数：

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

返回：

{
  "success": true,
  "page_uid": "target-page-uid",
  "parent_uid": "header-block-uid",
  "created_uids": ["uid1", "uid2", ...]
}

添加待办事项

向今天的每日页面添加一个或多个待办事项：

use_mcp_tool roam-research roam_add_todo {
  "todos": [
    "First todo item",
    "Second todo item",
    "Third todo item"
  ]
}

功能：

• 使用 Roam 复选框语法添加待办事项 ({{TODO}} todo text)
• 支持在单个操作中添加多个待办事项
• 在添加 >10 个待办事项时使用批量操作以提高效率
• 如果今天的页面不存在，则自动创建
• 以顺序方式将待办事项添加为顶级块

导入嵌套 Markdown

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

use_mcp_tool roam-research roam_import_markdown {
  "content": "- Item 1\n  - Subitem A\n  - Subitem B\n- Item 2",
  "page_uid": "optional-page-uid",
  "page_title": "optional-page-title",
  "parent_uid": "optional-parent-block-uid",
  "parent_string": "optional-exact-block-content",
  "order": "first"
}

功能：

• 在特定块下导入内容：
  • 按 UID 或精确字符串匹配查找父块
  • 按标题或 UID 在特定页面中查找块
  • 如果未指定页面，则默认为今天的页面
• 控制内容放置：
  • 添加为父块的第一个或最后一个子项
  • 保持层次结构
  • 用于嵌套内容的高效批量操作
• 全面的返回值：

  {
    "success": true,
    "page_uid": "target-page-uid",
    "parent_uid": "parent-block-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": "optional-block-uid",
  "page_title_uid": "optional-page-title-or-uid"
}

功能：

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

参数：

• block_uid: 要查找其引用的块的 UID（可选）
• page_title_uid: 要在其中搜索的页面的标题或 UID（可选）

返回：

{
  "success": true,
  "matches": [
    {
      "block_uid": "referenced-block-uid",
      "content": "Block content with ((reference))",
      "page_title": "Page containing reference"
    }
  ],
  "message": "Found N block(s) referencing..."
}

按文本搜索

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

use_mcp_tool roam-research roam_search_by_text {
  "text": "search text",
  "page_title_uid": "optional-page-title-or-uid",
  "case_sensitive": true
}

功能：

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

参数：

• text: 要搜索的文本（必需）
• page_title_uid: 要在其中搜索的页面的标题或 UID（可选）
• case_sensitive: 是否执行区分大小写的搜索（可选，默认为 true 以匹配 Roam 的本机行为）

返回：

{
  "success": true,
  "matches": [
    {
      "block_uid": "matching-block-uid",
      "content": "Block content containing search text",
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) containing \"search text\""
}

更新块内容

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

use_mcp_tool roam-research roam_update_block {
  "block_uid": "target-block-uid",
  "content": "New block content"
}

或者使用基于模式的转换：

use_mcp_tool roam-research roam_update_block {
  "block_uid": "target-block-uid",
  "transform_pattern": {
    "find": "\\bPython\\b",
    "replace": "[[Python]]",
    "global": true
  }
}

功能：

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

参数：

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

返回：

{
  "success": true,
  "content": "Updated block content"
}

搜索标签

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

use_mcp_tool roam-research roam_search_for_tag {
  "primary_tag": "Project/Tasks",
  "page_title_uid": "optional-page-title-or-uid",
  "near_tag": "optional-secondary-tag",
  "case_sensitive": true
}

功能：

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

参数：

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

返回：

{
  "success": true,
  "matches": [
    {
      "block_uid": "matching-block-uid",
      "content": "Block content containing #[[primary_tag]]",
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) referencing \"primary_tag\""
}

记住信息

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

use_mcp_tool roam-research roam_remember {
  "memory": "Important information to remember",
  "categories": ["Work", "Project/Alpha"]
}

功能：

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

参数：

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

返回：

{
  "success": true,
  "block_uid": "created-block-uid",
  "content": "Memory content with tags"
}

按日期搜索

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

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": "Found N matches for the given date range and criteria"
}

查找今天修改的页面

查找自今天午夜以来已修改的所有页面：

use_mcp_tool roam-research roam_find_pages_modified_today {}

功能：

• 跟踪自午夜以来对页面所做的所有修改
• 检测块层次结构中任何级别的更改
• 返回已修改页面的唯一列表
• 包括已修改页面的计数
• 无需参数

返回：

{
  "success": true,
  "pages": ["Page 1", "Page 2"],
  "message": "Found 2 page(s) modified today"
}

执行 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": "[result data]",
      "block_uid": "",
      "page_title": ""
    }
  ],
  "message": "Query executed successfully. Found N results."
}

示例查询：

1. 计算所有页面：

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

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

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

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

[: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": "optional-parent-block-uid",
  "child_uid": "optional-child-block-uid",
  "page_title_uid": "optional-page-title-or-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": "Block content",
      "depth": 2,
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) as children/parents..."
}

错误处理

该服务器为常见场景提供全面的错误处理：

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

每个错误响应包括：

• 标准 MCP 错误代码
• 详细的错误消息
• 适用时提供解决方案建议

开发

构建

要构建服务器：

npm install
npm run build

这将：

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

您还可以在开发期间使用 npm run watch 在文件更改时自动重新编译。

使用 MCP Inspector 进行测试

MCP Inspector 是一种帮助测试和调试 MCP 服务器的工具。 要测试服务器：

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

这将：

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

许可证

MIT 许可证