Skip to main content
Glama

漫游研究 MCP 服务器

npm 版本 项目状态:WIP – 初步开发正在进行中,但尚未有适合公众使用的稳定、可用的版本。 许可证:MIT GitHub

一个模型上下文协议 (MCP) 服务器,提供对 Roam Research API 功能的全面访问。该服务器使 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

Related MCP server: Roam Research MCP Server

测试

构建后运行MCP Inspector ...

npx @modelcontextprotocol/inspector node build/index.js

特征

该服务器提供了与 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 :在漫游图上执行自定义数据日志查询,以进行高级数据检索和分析

设置

  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"
  ]
}

特征:

  • 使用漫游复选框语法添加待办事项( {{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 :是否按“创建”、“修改”或“两者”进行搜索(必需)

  • scope :是否搜索“块”、“页面”或“两者”(必需)

  • 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 查询

在漫游图上执行自定义数据日志查询以进行高级数据检索和分析:

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

特征:

  • 直接访问 Roam 的查询引擎

  • 支持所有Datalog查询功能:

    • 复杂模式匹配

    • 聚合函数(计数、总和、最大值、最小值、平均值、不同)

    • 字符串操作(包括?、以...开头?、以...结尾?)

    • 逻辑运算(<、>、<=、>=、=、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]]
  1. 不区分大小写的文本搜索:

[: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]]
  1. 查找在某个日期之后修改的块:

[: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 检查器是一款用于测试和调试 MCP 服务器的工具。要测试服务器,请执行以下操作:

# Inspect with npx:
npx @modelcontextprotocol/inspector node build/index.js

这将:

  1. 以检查器模式启动服务器

  2. 提供交互式界面来:

    • 列出可用的工具和资源

    • 使用自定义参数执行工具

    • 查看工具响应和错误处理

执照

MIT 许可证

Available Tools

25 tools
roam_add_todoA

Add a list of todo items as individual blocks to today's daily page in Roam. Each item becomes its own actionable block with todo status. NOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use alias syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: todos (required), graph, write_key. Returns: success

roam_create_outlineA

Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels. To create a new page with an outline, use the roam_create_page tool instead. The outline parameter defines new blocks to be created. To nest content under an existing block, provide its UID or exact text in block_text_uid, and ensure the outline array contains only the child blocks with levels relative to that parent. Including the parent block's text in the outline array will create a duplicate block. Best for:

  • Adding supplementary structured content to existing pages

  • Creating temporary or working outlines (meeting notes, brainstorms)

  • Organizing thoughts or research under a specific topic

  • Breaking down subtopics or components of a larger concept Best for simpler, contiguous hierarchical content. For complex nesting (e.g., tables) or granular control over block placement, consider roam_process_batch_actions instead. API Usage Note: This tool performs verification queries after creation. For large outlines (10+ items) or when rate limits are a concern, consider using roam_process_batch_actions instead to minimize API calls.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: outline (required), graph, order, write_key, +2 more. Returns: success, page_uid, parent_uid, created_blocks

roam_create_pageA

Create a new standalone page in Roam with optional content, including structured outlines and tables, using explicit nesting levels and headings (H1-H3). This is the preferred method for creating a new page with an outline in a single step. Best for:

  • Creating foundational concept pages that other pages will link to/from

  • Establishing new topic areas that need their own namespace

  • Setting up reference materials or documentation

  • Making permanent collections of information

  • Creating pages with mixed text and table content in one call. Efficiency Tip: This tool batches page and content creation efficiently. For adding content to existing pages, use roam_process_batch_actions instead.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: title (required), graph, content, write_key. Returns: success, page_uid

roam_create_tableA

Create a table in Roam with specified headers and rows. This tool abstracts the complex nested structure that Roam tables require, making it much easier to create properly formatted tables.

Why use this tool:

  • Roam tables require precise nested block structures that are error-prone to create manually

  • Automatically handles the {{[[table]]}} container and nested column structure

  • Validates row/column consistency before execution

  • Converts empty cells to spaces (required by Roam)

Example: A table with headers ["", "Column A", "Column B"] and rows [{label: "Row 1", cells: ["A1", "B1"]}] creates a 2x3 table.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: rows (required), headers (required), parent_uid (required), graph, +2 more. Returns: error, success, uid_map, committed, +3 more

roam_datomic_queryA
Read-onlyIdempotent

Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. This provides direct access to Roam's query engine. Note: Roam graph is case-sensitive.

Optimal Use Cases for roam_datomic_query:

  • Advanced Filtering (including Regex): Use for scenarios requiring complex filtering, including regex matching on results post-query, which Datalog does not natively support for all data types. It can fetch broader results for client-side post-processing.

  • Highly Complex Boolean Logic: Ideal for intricate combinations of "AND", "OR", and "NOT" conditions across multiple terms or attributes.

  • Arbitrary Sorting Criteria: The go-to for highly customized sorting needs beyond default options.

  • Proximity Search: For advanced search capabilities involving proximity, which are difficult to implement efficiently with simpler tools.

List of some of Roam's data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text). Predicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=). Aggregates (distinct, count, sum, max, min, avg, limit). Tips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: query (required), graph, inputs, write_key, +3 more.

roam_fetch_blockA
Read-onlyIdempotent

Fetch a block by its UID with optional children (down to a specified depth) and/or ancestors (up to page root). Returns the block's UID, text, order, children array, and optionally an ancestors array with the chain to the page root.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: block_uid (required), depth, graph, write_key, +1 more.

roam_fetch_page_by_titleA
Read-onlyIdempotent

Fetch page by title. Returns content in the specified format.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: title (required), graph, format, write_key.

roam_fetch_page_full_viewA
Read-onlyIdempotent

Fetch a complete page view that mirrors what Roam Research shows in its UI: the page's own content, plus all linked references (backlinks) grouped by source page, each with their ancestor breadcrumb context and children expanded to the specified depth. Use this when you need the full picture of a page — both what is written on it and everything else in the graph that references it.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: title (required), graph, write_key, children_depth, +1 more.

roam_find_pages_modified_todayA
Read-onlyIdempotent

Find pages that have been modified today (since midnight), with pagination and sorting options.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, limit, offset, write_key, +1 more.

roam_get_guidelinesA
Read-onlyIdempotent

Retrieve this graph's user-defined agent conventions, read from the [[roam/agent guidelines]] page inside the graph (configurable per graph). These are the user's own rules — how they tag, how they name and namespace pages, what to never do, how they want your voice attributed.

Also returns roamSyntax: the rules whose violation destroys content — whole-page rewrites that delete, truncated previews written back as content, retyped block references, and the syntax that differs from standard markdown. These are returned on every call, including when the graph has no guidelines page, and they hold regardless of what the conventions say.

Call this ONCE per graph per session, before other tools, INCLUDING for reads: conventions change how results should be interpreted and presented, not just how content is written. Returns today's daily note title as orientation.

Distinct from roam_markdown_cheatsheet, which is the complete syntax reference — components, queries, embeds, tool selection. Call that when you need to look something up; this one you need before writing at all. Returns exists:false rather than failing when no page has been created.

Inputs: graph, write_key.

roam_get_subpagesA
Read-onlyIdempotent

Fetch all sub-pages (namespace children) of a given page prefix. Matches by page title prefix — pages titled "Prefix/Something" are sub-pages of "Prefix" and appear in the Hierarchy section of that page. This is namespace/title-prefix matching, distinct from roam_search_hierarchy which traverses block parent/child relationships. Optionally filter to only sub-pages containing a specific tag (e.g. filter active projects with filter_tag="active"), and optionally include each sub-page's full block content.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: prefix (required), graph, write_key, filter_tag, +1 more.

roam_import_markdownA

Import nested markdown content into Roam under a specific block. Can locate the parent block by UID (preferred) or by exact string match within a specific page. If a parent_string is provided and the block does not exist, it will be created. Returns a nested structure of the created blocks. API Usage Note: This tool fetches the full nested structure after import for verification. For large imports or when rate limits are a concern, consider using roam_process_batch_actions with pre-structured actions instead.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: content (required), graph, order, page_uid, +4 more. Returns: success, page_uid, parent_uid, created_blocks

roam_markdown_cheatsheetA
Read-onlyIdempotent

Provides the comprehensive Roam syntax reference. Covers: formatting, links & references (page refs, block refs, embeds including embed-children and embed-path), tags, dates, tasks, callouts, attributes, queries (native {{query}} with its clause rules and page-ref inheritance, plus :q Datalog tables with built-in rules), tables, kanban, mermaid diagrams (with theme support), advanced components (dropdowns, tooltips, templates, document mode, word-count), CSS tags (#.rm-E, #.rm-hide, etc.), anti-patterns, tool selection guide, and API efficiency tips.

IMPORTANT: Always load this cheatsheet before creating or updating Roam content. It prevents common syntax errors and guides tool selection.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, write_key.

roam_move_blockA
DestructiveIdempotent

Move a block to a new location (different parent or position). This is a convenience wrapper around roam_process_batch_actions for single block moves.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: block_uid (required), parent_uid (required), graph, order, +1 more. Returns: order, success, block_uid, new_parent_uid

roam_process_batch_actionsA
Destructive

RATE LIMIT EFFICIENT: This is the most API-efficient tool for multiple block operations. Combine all create/update/delete operations into a single call whenever possible. For intensive page updates or revisions, prefer this tool over multiple sequential calls.

Executes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Actions are executed in the provided order.

UID Placeholders for Nested Blocks: Use {{uid:name}} syntax for parent-child references within the same batch. The server generates proper random UIDs and returns a uid_map showing placeholder→UID mappings. Example: { uid: "{{uid:parent1}}", string: "Parent" } then { location: { "parent-uid": "{{uid:parent1}}" }, string: "Child" }. Response includes { success: true, uid_map: { "parent1": "Xk7mN2pQ9" } }.

For actions on existing blocks, a valid block UID is required. Note: Roam-flavored markdown, including block embedding with ((UID)) syntax, is supported within the string property for create-block and update-block actions. For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs. Tools like roam_fetch_page_by_title or other search tools can be used to retrieve these UIDs before executing batch actions. For simpler, sequential outlines, roam_create_outline is often more suitable.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: actions (required), graph, write_key. Returns: error, success, uid_map, committed, +2 more

roam_recallA
Read-onlyIdempotent

Retrieve all stored memories on page titled ROAM_MEMORIES_TAG, or tagged block content with the same name. Returns a combined, deduplicated list of memories. Optionally filter blocks with a specific tag and sort by creation date.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, sort_by, write_key, filter_tag.

roam_rememberA

Add a memory or piece of information to remember, stored on the daily page with ROAM_MEMORIES_TAG tag and optional categories (unless include_memories_tag is false). NOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use alias syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: memory (required), graph, heading, write_key, +3 more. Returns: success, block_uid, parent_uid

roam_rename_pageA
DestructiveIdempotent

Rename a page by changing its title. Identifies the page by current title or UID.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: new_title (required), uid, graph, old_title, +1 more. Returns: message, success

roam_search_block_refsA
Read-onlyIdempotent

Search for block references within a page or across the entire graph. Can search for references to a specific block, a page title, or find all block references.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, title, block_uid, write_key, +1 more.

roam_search_by_dateA
Read-onlyIdempotent

Search for blocks or pages based on creation or modification dates. Not for daily pages with ordinal date titles.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: type (required), scope (required), start_date (required), graph, +3 more.

roam_search_by_statusA
Read-onlyIdempotent

Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: status (required), graph, exclude, include, +2 more.

roam_search_by_textA
Read-onlyIdempotent

Search for blocks containing specific text across all pages or within a specific page. Use scope: "page_titles" to search for pages by namespace prefix (e.g., "Convention/" finds all pages starting with that prefix). This tool supports pagination via the limit and offset parameters. Pagination follows hidden-block filtering; block results use UID order and namespace results use title order.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: text (required), graph, limit, scope, +4 more.

roam_search_for_tagA
Read-onlyIdempotent

Search for blocks containing a specific tag. Use primary_tag for the tag to find, and optionally page_title_uid to limit search to a specific page. Supports pagination via limit and offset, applied after hidden-block filtering in UID order. Use this tool to search for memories tagged with the ROAM_MEMORIES_TAG.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: primary_tag (required), graph, limit, offset, +4 more.

roam_search_hierarchyA
Read-onlyIdempotent

Search for parent or child blocks in the block hierarchy. Can search up or down the hierarchy from a given block.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, child_uid, max_depth, write_key, +2 more.

roam_update_page_markdownA
DestructiveIdempotent

Update an existing page with new markdown content using smart diff. Preserves block UIDs where possible and generates minimal changes. This is ideal for:

  • Syncing external markdown files to Roam

  • AI-assisted content updates that preserve references

  • Batch content modifications without losing block references

⚠️ This REPLACES the page, it does not append. Any block your markdown does not account for is deleted. Pass the complete intended page, or use roam_process_batch_actions / roam_create_outline to change only part of one. Use dry_run: true to see the actions first.

How it works:

  1. Fetches existing page blocks

  2. Matches new content to existing blocks by text similarity

  3. Generates minimal create/update/move/delete operations

  4. Preserves UIDs for matched blocks (keeping references intact)

#.rm-hide / #.rm-private subtrees are excluded from the diff and left untouched — you cannot see them, so you cannot be asked to account for them. preserved_hidden reports how many, when any.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: title (required), markdown (required), graph, dry_run, +1 more. Returns: stats, actions, success, summary, +2 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools target distinct resources or actions, and the descriptions explicitly differentiate nearby tools such as roam_create_page vs. roam_create_outline vs. roam_process_batch_actions, and roam_fetch_page_by_title vs. roam_fetch_page_full_view. Some overlap remains, especially between namespace/page-title search and subpage retrieval, or between date search and modified-today search, but the boundaries are generally clear enough for tool selection.

    Naming Consistency4/5

    All tools share a consistent roam_ prefix and snake_case formatting, which makes the set predictable. The pattern is mostly roam_verb_noun, though a few names such as roam_markdown_cheatsheet and roam_datomic_query are noun-oriented rather than strict verb-object forms.

    Tool Count3/5

    With 25 tools, this is a heavy surface for an MCP server, even for a complex graph tool like Roam. The tools are mostly justified by distinct operations, but the set is large enough that an agent may need extra care to choose efficiently, especially across the many search and content-creation variants.

    Completeness4/5

    The surface covers most core Roam workflows: page creation, fetching, renaming, markdown updates, block fetching, moving, searching, batch block operations, tables, todos, memories, and references. Minor gaps remain, such as no explicit page deletion tool and block updates/deletes only being exposed through the broader batch-actions tool.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables Claude Desktop to read from and write to Roam Research graphs, allowing for retrieving page content, finding references, and adding blocks to existing or daily pages.
      4
      1
      -
    • A
      license
      A
      quality
      Not graded
      maintenance
      Enables AI assistants to interact with Roam Research graphs through comprehensive API access, supporting page/block operations, markdown import, search, memory storage, and complex batch actions for managing knowledge graphs.
      18
      404 npm
      -