The Roam Research MCP server enables AI assistants to programmatically interact with Roam Research graphs through a standardized interface, providing comprehensive read and write operations:
- Content retrieval: Fetch pages by title, search for specific text, dates, block references, or pages modified today
- Content creation: Create new pages, blocks, hierarchical outlines, or import markdown
- Content management: Add todos, update blocks (individually or in batch), store and recall memories
- Advanced search: Search by tags, status (TODO/DONE), hierarchy, or execute custom Datomic/Datalog queries
- Automation: Perform batch operations and efficiently handle nested content structures
This allows AI assistants to fully leverage Roam's database capabilities for both retrieving and manipulating graph content.
Supports loading configuration from .env files for managing environment variables like API tokens and graph names.
Enables parsing and conversion of markdown content, with support for importing nested markdown structures into Roam Research with proper hierarchy preservation.
Provides comprehensive access to Roam Research's API functionality, allowing AI assistants to interact with Roam Research graphs through tools for fetching, creating, and updating pages and blocks, importing markdown, searching content, and executing Datalog queries.
Roam Research MCP Server
A Model Context Protocol (MCP) server that provides 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. It supports standard input/output (stdio), HTTP Stream, and Server-Sent Events (SSE) communication. (A WORK-IN-PROGRESS, personal project not officially endorsed by Roam Research)
Installation and Usage
This MCP server supports three primary communication methods:
- Stdio (Standard Input/Output): Ideal for local inter-process communication, command-line tools, and direct integration with applications running on the same machine. This is the default communication method when running the server directly.
- HTTP Stream: Provides network-based communication, suitable for web-based clients, remote applications, or scenarios requiring real-time updates over HTTP. The HTTP Stream endpoint runs on port
8088
by default. - SSE (Server-Sent Events): A transport for legacy clients that require SSE. The SSE endpoint runs on port
8087
by default. (NOTE: ⚠️ DEPRECATED: The SSE Transport has been deprecated as of MCP specification version 2025-03-26. HTTP Stream Transport preferred.)
Running with Stdio
You can install the package globally and run it:
Or clone the repository and build from source:
Running with HTTP Stream
To run the server with HTTP Stream or SSE support, you can either:
- Use the default ports: Run
npm start
after building (as shown above). The server will automatically listen on port8088
for HTTP Stream and8087
for SSE. - Specify custom ports: Set the
HTTP_STREAM_PORT
and/orSSE_PORT
environment variables before starting the server.Or, if using a.env
file, addHTTP_STREAM_PORT=9000
and/orSSE_PORT=9001
to it.
Docker
This project can be easily containerized using Docker. A Dockerfile
is provided at the root of the repository.
Build the Docker Image
To build the Docker image, navigate to the project root and run:
Run the Docker Container
To run the Docker container and map the necessary ports, you must also provide the required environment variables. Use the -e
flag to pass ROAM_API_TOKEN
, ROAM_GRAPH_NAME
, and optionally MEMORIES_TAG
, HTTP_STREAM_PORT
, and SSE_PORT
:
Alternatively, if you have a .env
file in the project root (which is copied into the Docker image during build), you can use the --env-file
flag:
To Test
Run MCP Inspector after build using the provided npm script:
Features
The server provides powerful tools for interacting with Roam Research:
- Environment variable handling with .env support
- Comprehensive input validation
- Case-insensitive page title matching
- Recursive block reference resolution
- Markdown parsing and conversion
- Daily page integration
- Detailed debug logging
- Efficient batch operations
- Hierarchical outline creation
- Enhanced documentation for Roam Tables in
Roam_Markdown_Cheatsheet.md
for clearer guidance on nesting.- Custom instruction appended to the cheat sheet about your specific Roam notes.
roam_fetch_page_by_title
: Fetch page content by title. Returns content in the specified format.roam_fetch_block_with_children
: Fetch a block by its UID along with its hierarchical children down to a specified depth. Automatically handles((UID))
formatting.roam_create_page
: Create new pages with optional content and headings. Now creates a block on the daily page linking to the newly created page.roam_import_markdown
: Import nested markdown content under a specific block. (Internally usesroam_process_batch_actions
.)roam_add_todo
: Add a list of todo items to today's daily page. (Internally usesroam_process_batch_actions
.)roam_create_outline
: Add a structured outline to an existing page or block, with support forchildren_view_type
. Best for simpler, sequential outlines. For complex nesting (e.g., tables), considerroam_process_batch_actions
. Ifpage_title_uid
andblock_text_uid
are both blank, content defaults to the daily page. (Internally usesroam_process_batch_actions
.)roam_search_block_refs
: Search for block references within a page or across the entire graph.roam_search_hierarchy
: Search for parent or child blocks in the block hierarchy.roam_find_pages_modified_today
: Find pages that have been modified today (since midnight).roam_search_by_text
: Search for blocks containing specific text.roam_search_by_status
: Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.roam_search_by_date
: Search for blocks or pages based on creation or modification dates.roam_search_for_tag
: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby.roam_remember
: Add a memory or piece of information to remember. (Internally usesroam_process_batch_actions
.)roam_recall
: Retrieve all stored memories.roam_datomic_query
: Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools.roam_markdown_cheatsheet
: Provides the content of the Roam Markdown Cheatsheet resource, optionally concatenated with custom instructions ifCUSTOM_INSTRUCTIONS_PATH
environment variable is set.roam_process_batch_actions
: Execute a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Provides granular control for complex nesting like tables. (Note: For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs using tools likeroam_fetch_page_by_title
.)
Deprecated Tools:
The following tools have been deprecated as of v.0.30.0
in favor of the more powerful and flexible roam_process_batch_actions
:
roam_create_block
: Useroam_process_batch_actions
with thecreate-block
action.roam_update_block
: Useroam_process_batch_actions
with theupdate-block
action.roam_update_multiple_blocks
: Useroam_process_batch_actions
with multipleupdate-block
actions.
Tool Usage Guidelines and Best Practices
Pre-computation and Context Loading:
✅ Before attempting any Roam operations, it is highly recommended to load the Roam Markdown Cheatsheet
resource into your context. This ensures you have immediate access to the correct Roam-flavored Markdown syntax, including details for tables, block references, and other special formatting. Example prompt: "Read the Roam cheatsheet first. Then, … "
- Specific notes and preferences concerning my Roam Research graph. Users can add their own specific notes and preferences for working with their own graph in the Cheatsheet.
Identifying Pages and Blocks for Manipulation: To ensure accurate operations, always strive to identify target pages and blocks using their Unique Identifiers (UIDs) whenever possible. While some tools accept case-sensitive text titles or content, UIDs provide unambiguous references, reducing the risk of errors due to ambiguity or changes in text.
- For Pages: Use
roam_fetch_page_by_title
to retrieve a page's UID if you only have its title. Example: "Read the page titled 'Trip to Las Vegas'" - For Blocks: If you need to manipulate an existing block, first use search tools like
roam_search_by_text
,roam_search_for_tag
, orroam_fetch_page_by_title
(with raw format) to find the block and obtain its UID. If the block exists on a page that has already been read, then a search isn't necessary.
Case-Sensitivity: Be aware that text-based inputs (e.g., page titles, block content for search) are generally case-sensitive in Roam. Always match the exact casing of the text as it appears in your graph.
Iterative Refinement and Verification: For complex operations, especially those involving nested structures or multiple changes, it is often beneficial to break down the task into smaller, verifiable steps. After each significant tool call, consider fetching the affected content to verify the changes before proceeding.
Understanding Tool Nuances:
Familiarize yourself with the specific behaviors and limitations of each tool. For instance, roam_create_outline
is best for sequential outlines, while roam_process_batch_actions
offers granular control for complex structures like tables. Refer to the individual tool descriptions for detailed usage notes.
When making changes to your Roam graph, precision in your requests is crucial for achieving desired outcomes.
Specificity in Requests:
Some tools allow for identifying blocks or pages by their text content (e.g., parent_string
, title
). While convenient, using Unique Identifiers (UIDs) is always preferred for accuracy and reliability. Text-based matching can be prone to errors if there are multiple blocks with similar content or if the content changes. Tools are designed to work best when provided with explicit UIDs where available.
Example of Specificity:
Instead of:
"parent_string": "My project notes"
Prefer:
"parent_uid": "((some-unique-uid))"
Caveat Regarding Heading Formatting:
Please note that while the roam_process_batch_actions
tool can set block headings (H1, H2, H3), directly removing an existing heading (i.e., reverting a heading block to a plain text block) through this tool is not currently supported by the Roam API. The heading
attribute persists its value once set, and attempting to remove it by setting heading
to 0
, null
, or omitting the property will not unset the heading.
Example Prompts
Here are some examples of how to creatively use the Roam tool in an LLM to interact with your Roam graph, particularly leveraging roam_process_batch_actions
for complex operations.
Example 1: Creating a Project Outline
This prompt demonstrates creating a new page and populating it with a structured outline using a single roam_process_batch_actions
call.
Example 2: Updating Multiple To-Dos and Adding a New One
This example shows how to mark existing to-do items as DONE
and add a new one, all within a single batch.
Example 3: Moving and Updating a Block
This demonstrates moving a block from one location to another and simultaneously updating its content.
Example 4: Making a Table
This demonstrates moving a block from one location to another and simultaneously updating its content.
Setup
- Create a Roam Research API token:
- Go to your graph settings
- Navigate to the "API tokens" section (Settings > "Graph" tab > "API Tokens" section and click on the "+ New API Token" button)
- Create a new token
- Configure the environment variables:
You have two options for configuring the required environment variables:Option 1: Using a .env file (Recommended for development)
Create a
.env
file in the roam-research directory:Option 2: Using MCP settings (Alternative method) Add the configuration to your MCP settings file. Note that you may need to update theargs
to["/path/to/roam-research-mcp/build/index.js"]
if you are running the server directly.- For Cline (
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
): - For Claude desktop app (
~/Library/Application Support/Claude/claude_desktop_config.json
):
Note: The server will first try to load from .env file, then fall back to environment variables from MCP settings.
- For Cline (
- Build the server (make sure you're in the root directory of the MCP):Note: Customize 'Roam_Markdown_Cheatsheet.md' with any notes and preferences specific to your graph BEFORE building.
Error Handling
The server provides comprehensive error handling for common scenarios:
- Configuration errors:
- Missing API token or graph name
- Invalid environment variables
- API errors:
- Authentication failures
- Invalid requests
- Failed operations
- Tool-specific errors:
- Page not found (with case-insensitive search)
- Block not found by string match
- Invalid markdown format
- Missing required parameters
- Invalid outline structure or content
Each error response includes:
- Standard MCP error code
- Detailed error message
- Suggestions for resolution when applicable
Development
Building
To build the server:
This will:
- Install all required dependencies
- Compile TypeScript to JavaScript
- Make the output file executable
You can also use npm run watch
during development to automatically recompile when files change.
Testing with MCP Inspector
The MCP Inspector is a tool that helps test and debug MCP servers. To test the server:
This will:
- Start the server in inspector mode
- Provide an interactive interface to:
- List available tools and resources
- Execute tools with custom parameters
- View tool responses and error handling
License
MIT License
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
Provides 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.
Related MCP Servers
- -securityFlicense-qualityThis server integrates DeepSeek and Claude AI models to provide enhanced AI responses, featuring a RESTful API, configurable parameters, and robust error handling.Last updated -13TypeScript
- -securityFlicense-qualityThis server enables AI assistants (CLINE, Cursor, Windsurf, Claude Desktop) to share a common knowledge base through Retrieval Augmented Generation (RAG), providing consistent information access across multiple tools.Last updated -4TypeScript
- -securityAlicense-qualityA 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.Last updated -4PythonMIT License
- -securityFlicense-qualityHigh-performance server enabling AI assistants to access web scraping, crawling, and deep research capabilities through Model Context Protocol.Last updated -11TypeScript