Roam Research MCP server

This server bridges AI assistants like Claude with your Roam Research database, allowing seamless interaction with your Roam graph through natural language. You can create new content, search existing information, store memories, and process external content from websites, PDFs, and YouTube videos without any coding.

Installation

Prerequisites

• Claude Desktop application installed from https://claude.ai/download
• A Roam Research account with API access

Basic Setup

1. Locate your Claude Desktop configuration file:

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Edit the configuration file to add the MCP server:

{
  "mcpServers": {
    "roam-helper": {
      "command": "uvx",
      "args": ["git+https://github.com/PhiloSolares/roam-mcp.git"],
      "env": {
        "ROAM_API_TOKEN": "<your_roam_api_token>",
        "ROAM_GRAPH_NAME": "<your_roam_graph_name>"
      }
    }
  }
}

3. Obtain your Roam API token:

   • Open your Roam Research graph
   • Go to graph settings
   • Navigate to "API tokens"
   • Click "+ New API Token"
   • Copy the generated token

4. Replace the placeholders in the configuration:

   • <your_roam_api_token> with your actual API token
   • <your_roam_graph_name> with your Roam graph name

Docker Installation (Alternative)

You can also run the server inside a Docker container:

1. Build the Docker image:

docker build -t roam-mcp .

2. Run the container with your credentials:

docker run -p 3000:3000 \
  -e ROAM_API_TOKEN="your_api_token" \
  -e ROAM_GRAPH_NAME="your_graph_name" \
  roam-mcp

3. Configure Claude Desktop to use the containerized server:

{
  "mcpServers": {
    "roam-helper": {
      "command": "docker",
      "args": ["run", "--rm", "-p", "3000:3000",
               "-e", "ROAM_API_TOKEN=your_token",
               "-e", "ROAM_GRAPH_NAME=your_graph",
               "roam-mcp"],
      "env": {}
    }
  }
}

Usage Examples

Once configured, you can start using Claude to interact with your Roam graph through natural language commands.

Creating Content

You can ask Claude to create new pages and content in your Roam graph:

• "Create a new page in Roam called 'Project Planning'"
• "Add these meeting notes to today's daily note in Roam"
• "Create an outline for my research paper on cognitive biases"
• "Add a TODO item to review the quarterly report by Friday"

Searching Your Roam Graph

Search for specific content with filtering options:

• "Search my Roam graph for blocks tagged with #ProjectIdeas"
• "Find all TODO items I created this month"
• "Show me all blocks that mention 'productivity' and 'habits'"
• "Find pages I've created in the last week about marketing strategies"

Using the Memory System

The MCP server includes a memory system to store information across conversations:

• "Remember that I want to focus on learning Spanish this quarter"
• "Remember that my project deadline is June 15th"
• "What have we discussed about my learning goals?"
• "Recall any memories related to project deadlines"

Processing External Content

Import and process content from external sources:

• "Extract the main points from this PDF and add them to my Roam graph"
• "Get the transcript from this YouTube video and create a new page with the key points"
• "Summarize this article and add it to my 'Research' page in Roam"

Advanced Configuration

Custom Memory Tags

By default, the memory system stores memories with the tag #[[Memories]]. You can customize this:

"env": {
  "ROAM_API_TOKEN": "your-token",
  "ROAM_GRAPH_NAME": "your-graph",
  "MEMORIES_TAG": "#[[Claude/Memories]]"
}

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-helper" '{"command":"uvx","args":["git+https://github.com/PhiloSolares/roam-mcp.git"],"env":{"ROAM_API_TOKEN":"<your_roam_api_token>","ROAM_GRAPH_NAME":"<your_roam_graph_name>"}}'

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-helper": {
            "command": "uvx",
            "args": [
                "git+https://github.com/PhiloSolares/roam-mcp.git"
            ],
            "env": {
                "ROAM_API_TOKEN": "<your_roam_api_token>",
                "ROAM_GRAPH_NAME": "<your_roam_graph_name>"
            }
        }
    }
}

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-helper": {
            "command": "uvx",
            "args": [
                "git+https://github.com/PhiloSolares/roam-mcp.git"
            ],
            "env": {
                "ROAM_API_TOKEN": "<your_roam_api_token>",
                "ROAM_GRAPH_NAME": "<your_roam_graph_name>"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect