Roam Research MCP Server
Enables retrieving content from Roam Research pages with nested blocks, finding page references, writing new blocks to existing pages, adding content to daily pages, and handling hierarchical block structures with proper markdown conversion.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Roam Research MCP Server add 'Meeting notes from the project kickoff' to today's daily page"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Roam Research MCP Server
A Model Context Protocol (MCP) server that provides tools to interact with Roam Research API, enabling Claude Desktop to read from and write to your Roam Research graph.
Features
Get Page Content: Retrieve content from any page with nested child blocks in markdown format
Get Page References: Find all references to a specific page with pagination support and time-based sorting
Write to Page: Add new blocks to existing pages
Write to Today: Add content to today's daily page (auto-creates if needed)
Markdown Conversion: Automatically converts Roam-style
[[links]]to markdown formatNested Block Support: Handles hierarchical block structures with proper indentation
Related MCP server: MCP Memory Server
Installation
Prerequisites
Python 3.11+
uv package manager
Roam Research API token and graph access
Setup
Clone the repository:
git clone <repository-url>
cd roam-research-mcpInstall dependencies:
uv syncSet up environment variables:
export ROAM_TOKEN="your_roam_research_api_token"
export ROAM_GRAPH_NAME="your_graph_name"Claude Desktop Integration
Add this configuration to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"roam-research": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/roam-research-mcp",
"run",
"python",
"main.py"
],
"env": {
"ROAM_TOKEN": "your_actual_roam_token",
"ROAM_GRAPH_NAME": "your_graph_name"
}
}
}
}Usage
Once configured with Claude Desktop, you can:
Ask Claude to read content from your Roam pages
Have Claude write notes and thoughts to your daily pages
Query page references and connections
Add structured content to specific pages
Development
See CLAUDE.md for development guidelines and git commit conventions.
API Requirements
Valid Roam Research API token
Graph name with API access enabled
Network access to
api.roamresearch.com
License
MIT License
Available Tools
4 toolsget_page_contentA
Get the complete content of a specific page in Roam Research with all nested child blocks.
Retrieves all blocks on the specified page with their hierarchical structure,
including nested children up to 5 levels deep. Returns content in markdown format
with proper indentation to reflect the block hierarchy.
Args:
page_name: Exact name of the page to retrieve (case-sensitive)
Returns:
JSON string containing:
- result: Array of blocks with content and timestamps
- Each block includes: content (markdown), timestamp (edit time)
Examples:
get_page_content("Daily Notes")
get_page_content("Project Planning")
get_page_content("信用卡")
Inputs: page_name (required). Returns: result
get_page_referencesA
Get all blocks that reference a specific page in Roam Research with pagination support.
Finds all blocks across your Roam database that contain links to the specified page.
Results are sorted by most recent edit time and include the full hierarchical context
of each referencing block.
Args:
page_name: Exact name of the page to find references for (case-sensitive)
limit: Maximum number of references to return per request (default: 10)
cursor: Timestamp cursor for pagination - use next_cursor from previous response
to get additional results
Returns:
JSON string containing:
- result: Array of referencing blocks with content and timestamps
- next_cursor: Timestamp for pagination (if more results available)
- total_matches: Number of references found in this batch
Examples:
get_page_references("GTD")
get_page_references("Project Alpha", limit=20)
get_page_references("Meeting Notes", limit=5, cursor=1640995200000)
Inputs: page_name (required), limit, cursor. Returns: result
write_to_pageA
Write hierarchical markdown content to a specific page in Roam Research.
Creates a new block structure on the specified page with automatic indentation
detection. Supports nested bullet points and maintains proper parent-child
relationships between blocks. Content is appended to the end of the page.
Args:
page_name: Exact name of the target page (case-sensitive, must exist)
content: Hierarchical markdown content using '- ' prefix and indentation
Format: "- Main topic
- Subtopic
- Details"
Supports any indentation level with automatic detection
Returns:
JSON string containing:
- result: "success" if completed
- blocks_created: Total number of blocks created (including children)
- details: Array of individual block creation results
Examples:
write_to_page("Project Notes", "- New milestone
- Task 1
- Task 2")
write_to_page("信用卡", "- [[銀行/國泰]]
- 現金回饋 2%")
Inputs: page_name (required), content (required). Returns: result
write_to_todayA
Write hierarchical markdown content to today's daily page in Roam Research.
Automatically creates today's daily page if it doesn't exist, then adds the
provided content as a hierarchical block structure. Uses Roam's standard
date format (e.g., "July 28, 2025") and maintains proper block relationships.
Args:
content: Hierarchical markdown content using '- ' prefix and indentation
Format: "- Main topic
- Subtopic
- Details"
Supports any indentation level with automatic detection
Returns:
JSON string containing:
- result: "success" if completed
- blocks_created: Total number of blocks created (including children)
- details: Array of individual block creation results
Examples:
write_to_today("- Daily standup
- Completed: Bug fixes
- Next: Feature review")
write_to_today("- [[會議/週會]]
- 參與者: @John, @Mary
- 議題: Q4 規劃")
Inputs: content (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose with no overlap: get_page_content retrieves page content, get_page_references finds references to pages, write_to_page writes to a specific page, and write_to_today writes to today's daily page. The separation between general page operations and the specialized daily page operation is well-defined, preventing confusion.
All tool names follow a consistent verb_noun pattern with snake_case: get_page_content, get_page_references, write_to_page, and write_to_today. The naming is predictable and readable, making it easy for agents to understand the action and target at a glance.
Four tools are reasonable for a Roam Research server, covering core read and write operations. However, the scope feels slightly thin as it lacks update or delete capabilities for existing blocks, which are common in note-taking workflows. The count is appropriate but could be more comprehensive.
The tools cover basic retrieval and creation for pages and daily notes, but there are notable gaps. Missing operations include updating or deleting existing blocks, searching across pages, and managing page metadata. This limits agents to read and append-only workflows, which may cause failures in more complex tasks.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
A self-hostable feed of reminders, learnings and work that Claude and ChatGPT can read and write
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides comprehensive access to Roam Research's API functionality. This server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface.25404 npm101MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server for Claude Desktop that provides structured memory management across chat sessions, allowing Claude to maintain context and build a knowledge base within project directories.11 npm7MIT
- 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

Roam MCPofficial
FlicenseNot gradedqualityCmaintenanceMCP server for Roam Research that enables AI assistants like Claude and Cursor to read, write, search, and query your Roam graph with full write access.62-