Roam Research MCP server

This MCP server provides a standardized interface for AI assistants like Claude to interact with your Roam Research graph. It supports multiple communication methods and offers a comprehensive set of tools to query, create, and modify content in Roam Research through API calls.

Installation

Basic Setup

1. Install the package globally:

npm install -g roam-research-mcp
roam-research-mcp

Or build from source:

git clone https://github.com/2b3pro/roam-research-mcp.git
cd roam-research-mcp
npm install
npm run build
npm start

Environment Configuration

Before using the server, you need to set up your Roam Research API token:

1. Create a Roam Research API token:

   • Go to your graph settings
   • Navigate to "API tokens" section
   • Click on "+ New API Token" button

2. Configure the environment variables using a .env file:

ROAM_API_TOKEN=your-api-token
ROAM_GRAPH_NAME=your-graph-name
MEMORIES_TAG='#[[LLM/Memories]]'
HTTP_STREAM_PORT=8088
SSE_PORT=8087

Communication Methods

The server supports three communication methods:

1. Standard Input/Output (Stdio): Default method when running the server directly
2. HTTP Stream: Network-based communication on port 8088 (default)
3. Server-Sent Events (SSE): Legacy transport on port 8087 (deprecated)

To run with custom ports:

HTTP_STREAM_PORT=9000 SSE_PORT=9001 npm start

Docker Deployment

To containerize with Docker:

# Build the image
docker build -t roam-research-mcp .

# Run the container with environment variables
docker run -p 3000:3000 -p 8088:8088 -p 8087:8087 \
  -e ROAM_API_TOKEN="your-api-token" \
  -e ROAM_GRAPH_NAME="your-graph-name" \
  -e MEMORIES_TAG="#[[LLM/Memories]]" \
  -e HTTP_STREAM_PORT="8088" \
  -e SSE_PORT="8087" \
  roam-research-mcp

Or with an environment file:

docker run -p 3000:3000 -p 8088:8088 --env-file .env roam-research-mcp

Usage

Testing

Run the MCP Inspector to test your server:

npm run inspector

Available Tools

The server provides the following tools for interacting with Roam Research:

1. Page Operations:

   • roam_fetch_page_by_title: Retrieve page content
   • roam_create_page: Create new pages with optional content
   • roam_find_pages_modified_today: Find pages modified today

2. Block Operations:

   • roam_process_batch_actions: Execute multiple block actions in a single batch
   • roam_import_markdown: Import nested markdown content
   • roam_create_outline: Add structured outlines to pages
   • roam_add_todo: Add todo items to the daily page

3. Search Operations:

   • roam_search_block_refs: Find block references
   • roam_search_hierarchy: Search parent/child blocks
   • roam_search_by_text: Find blocks containing specific text
   • roam_search_by_status: Find TODO/DONE blocks
   • roam_search_by_date: Search by creation/modification dates
   • roam_search_for_tag: Find blocks with specific tags

4. Memory Operations:

   • roam_remember: Store information to remember
   • roam_recall: Retrieve stored memories

5. Advanced Operations:

   • roam_datomic_query: Execute custom Datomic queries

Best Practices

1. Pre-computation and Context Loading:

   • Load the Roam Markdown Cheatsheet resource before operations

2. Using Unique Identifiers:

   • Use UIDs for targeting pages and blocks whenever possible
   • Get UIDs with roam_fetch_page_by_title if you only have titles

3. Case-Sensitivity:

   • Text inputs (page titles, block content) are case-sensitive

4. Iterative Operations:

   • Break complex tasks into smaller, verifiable steps
   • Verify changes after each significant operation

5. Tool Selection:

   • Use roam_create_outline for simple sequential outlines
   • Use roam_process_batch_actions for complex structures like tables

Example Usage

Creating a Project Outline:

"Create a new Roam page titled 'Project Alpha Planning' and add the following outline:
- Overview
  - Goals
  - Scope
- Team Members
  - John Doe
  - Jane Smith
- Tasks
  - Task 1
    - Subtask 1.1
    - Subtask 1.2
  - Task 2
- Deadlines"

Managing To-Dos:

"Mark 'Finish report' and 'Review presentation' as done on today's daily page, and add a new todo 'Prepare for meeting'."

Creating Tables:

"In Roam, add a new table on the page "Fruity Tables" that compares four types of fruits: apples, oranges, grapes, and dates. Choose randomly four areas to compare."

Error Handling

The server provides comprehensive error handling for common scenarios:

• Configuration errors (missing API token, invalid variables)
• API errors (authentication failures, invalid requests)
• Tool-specific errors (page not found, invalid formats)

Each error response includes a standard MCP error code, detailed message, and resolution suggestions when applicable.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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]]"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect