Roam Research MCP server for AI agents

The Roam Research MCP server is a powerful interface that allows AI assistants like Claude to interact with your Roam Research graph through a standardized protocol. It provides comprehensive access to Roam Research's API functionality, enabling you to fetch, create, and manipulate data in your knowledge graph programmatically.

Installation

You can install the package globally using npm:

npm install -g roam-research-mcp

Alternatively, you can clone the repository and build from source:

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

Setup

Step 1: Create a Roam Research API Token

Go to your Roam Research graph settings
Navigate to the "API tokens" section (Settings > "Graph" tab > "API Tokens")
Click the "+ New API Token" button to create a new token

Step 2: Configure 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:

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

Option 2: Using MCP settings

Add the configuration to your MCP settings file:

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

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

Step 3: Build the Server

cd roam-research-mcp
npm install
npm run build

Usage

Fetching Page Content

To fetch and read a page's content with resolved block references:

use_mcp_tool roam-research roam_fetch_page_by_title {
  "title": "Example Page"
}

This returns the page content as markdown with complete hierarchical structure and block references resolved up to 4 levels deep.

Creating Pages

To create a new page with optional content:

use_mcp_tool roam-research roam_create_page {
  "title": "New Page",
  "content": "Initial content for the page"
}

Adding Blocks

To add a new block to a page:

use_mcp_tool roam-research roam_create_block {
  "content": "Block content",
  "page_uid": "optional-target-page-uid",
  "title": "optional-target-page-title"
}

If neither page_uid nor title is provided, the block will be added to today's daily page.

Creating Hierarchical Outlines

To create a structured outline with proper nesting:

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

Adding Todo Items

To add multiple todo items to today's daily page:

use_mcp_tool roam-research roam_add_todo {
  "todos": [
    "First todo item",
    "Second todo item",
    "Third todo item"
  ]
}

Importing Markdown Content

To import nested markdown content under a specific block:

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

Searching for Block References

To search for block references within pages or across the graph:

use_mcp_tool roam-research roam_search_block_refs {
  "block_uid": "optional-block-uid",
  "page_title_uid": "optional-page-title-or-uid"
}

Text Search

To search for blocks containing specific text:

use_mcp_tool roam-research roam_search_by_text {
  "text": "search text",
  "page_title_uid": "optional-page-title-or-uid",
  "case_sensitive": true
}

Updating Block Content

To update a block's content using direct text replacement:

use_mcp_tool roam-research roam_update_block {
  "block_uid": "target-block-uid",
  "content": "New block content"
}

Or using pattern-based transformation:

use_mcp_tool roam-research roam_update_block {
  "block_uid": "target-block-uid",
  "transform_pattern": {
    "find": "\\bPython\\b",
    "replace": "[[Python]]",
    "global": true
  }
}

Searching for Tags

To search for blocks containing specific tags:

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
}

Storing and Recalling Information

To remember important information:

use_mcp_tool roam-research roam_remember {
  "memory": "Important information to remember",
  "categories": ["Work", "Project/Alpha"]
}

To recall stored memories:

use_mcp_tool roam-research roam_recall {
  "categories": ["optional-category-filter"]
}

Date-Based Search

To search for blocks and pages based on creation or modification dates:

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
}

Finding Pages Modified Today

To find all pages modified since midnight:

use_mcp_tool roam-research roam_find_pages_modified_today {}

Running Custom Datomic Queries

To execute custom Datalog queries on your Roam graph:

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

Example queries:

Count all pages:

[:find (count ?p)
 :where [?p :node/title]]

Case-insensitive text search:

[: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]]

Searching Block Hierarchy

To navigate and search through block parent-child relationships:

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
}

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.