Roam Research
漫游研究 MCP 服务器
一个模型上下文协议 (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 buildRelated MCP server: Roam Research MCP Server
测试
构建后运行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:在漫游图上执行自定义数据日志查询,以进行高级数据检索和分析
设置
转到图表设置
导航到“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": "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:包含父块的页面的 UIDpage_title:包含父块的页面标题(如果提供了 page_uid 则忽略)parent_uid:要添加内容的父块的 UIDparent_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."
}示例查询:
统计所有页面:
[: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 "search term")]
[?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": "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这将:
安装所有必需的依赖项
将 TypeScript 编译为 JavaScript
使输出文件可执行
您还可以在开发过程中使用npm run watch在文件发生更改时自动重新编译。
使用 MCP Inspector 进行测试
MCP 检查器是一款用于测试和调试 MCP 服务器的工具。要测试服务器,请执行以下操作:
# Inspect with npx:
npx @modelcontextprotocol/inspector node build/index.js这将:
以检查器模式启动服务器
提供交互式界面来:
列出可用的工具和资源
使用自定义参数执行工具
查看工具响应和错误处理
执照
MIT 许可证
Available Tools
25 toolsroam_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_actionsinstead. API Usage Note: This tool performs verification queries after creation. For large outlines (10+ items) or when rate limits are a concern, consider usingroam_process_batch_actionsinstead 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_actionsinstead.
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_queryARead-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_blockARead-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_titleARead-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_viewARead-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_todayARead-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_guidelinesARead-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_subpagesARead-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_cheatsheetARead-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_blockADestructiveIdempotent
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_actionsADestructive
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_recallARead-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_pageADestructiveIdempotent
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_refsARead-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_dateARead-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_statusARead-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_textARead-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_tagARead-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_hierarchyARead-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_markdownADestructiveIdempotent
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:
Fetches existing page blocks
Matches new content to existing blocks by text similarity
Generates minimal create/update/move/delete operations
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
Scored across 25 tools
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.
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.
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.
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
Related MCP Connectors
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Hosted Notion MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted Airtable MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Official Fibery MCP server: query and update your workspace from any AI client via OAuth.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides a standardized interface for AI assistants to interact with Obsidian vaults through a local REST API, enabling reading, writing, searching, and managing notes.69MIT
- AlicenseNot gradedqualityDmaintenanceA server that enables AI assistants like Claude to interact with Roam Research graphs through a standardized interface, providing comprehensive tools for content creation, search, retrieval, and optional memory management.8MIT
- FlicenseAqualityDmaintenanceA 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.41-
- AlicenseAqualityNot gradedmaintenanceEnables 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.18404 npm-