Roam MCP Server

How to use

You connect Claude to your Roam graph through MCP configuration, then start Claude and your Roam MCP server. Once running, you can ask Claude to create pages, add blocks, search by title or tag, retrieve lists of TODOs, and even extract content from external sources and add it to Roam. Use plain language to describe what you want, and Claude will translate your request into Roam actions.

Examples of practical uses include creating a new Roam page with a structured outline, adding nested blocks under a page, importing markdown into Roam with proper nesting, tagging memories for later recall, and querying Roam content by date, tag, or hierarchy. You can also use the memory system to store reminders or decisions and retrieve them later with filtering.

How to install

Prerequisites: you need a working environment with Docker installed and access to Claude Desktop. You should also have a Roam Research graph and an API token for that graph.

Step 1: Install Claude Desktop on your computer by downloading it from the official Claude site.

Step 2: Create or edit your Claude Desktop configuration to add an MCP server entry. You will configure a local Roam MCP server using uvx and point it to your Roam graph.

Step 3: Define the Roam MCP server in your Claude configuration. The following snippet shows a complete configuration for a local MCP server that connects to Roam via an API token and Graph name.

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

Advanced setup using Docker

You can run the Roam MCP server inside a Docker container. This approach isolates the server from your local environment and makes it easy to manage.

Start the container with the required tokens and graph name, then configure Claude Desktop to connect to the containerized server.

Example commands to run locally and to configure Claude Desktop to use the container are shown below.

# Build the image (if you have a Dockerfile)
docker build -t roam-mcp .

# Run the container with your Roam API token and graph name
docker run -p 3000:3000 \
  -e ROAM_API_TOKEN="your_token" \
  -e ROAM_GRAPH_NAME="your_graph" \
  roam-mcp
```
```json
{
  "mcpServers": {
    "roam_helper_docker": {
      "command": "docker",
      "args": ["run", "--rm", "-p", "3000:3000", "-e", "ROAM_API_TOKEN=your_token", "-e", "ROAM_GRAPH_NAME=your_graph", "roam-mcp"]
    }
  }
}

Create pages

Create a new Roam page with a specified title and optional nested content and headings.

Add blocks

Add content blocks to a page, maintaining proper hierarchy and nesting.

Create outlines

Generate structured outlines with customizable nesting within Roam pages.

Import markdown

Import Markdown content and preserve nesting relationships inside Roam.

Add todo items

Create to-do items with automatic TODO status and hierarchical placement.

Update content

Update existing content either individually or in batches.

Modify block content

Transform block content with pattern-based changes.

Find by title

Search for pages by title within the Roam graph.

Find by text

Search for blocks containing specific text across the graph.

Find by tags

Locate blocks or pages by tag names or tags in content.

Search TODOs

Filter and retrieve TODO/DONE items with various criteria.

Recently modified

Identify content that has been recently modified.

Block references

Explore block references and navigate block hierarchies.

Block hierarchies

Navigate parent-child relationships among blocks.

Creation/modification dates

Search by creation or modification dates.

Datalog queries

Execute custom Datalog queries for advanced data retrieval.

Memory storage

Store information for Claude to remember across conversations.

Memory recall

Recall stored memories with filtering and sorting options.

Memory tagging

Tag memories with custom categories for organization.

Memory retrieval

Access memories from both recent and older entries.

URL content extraction

Extract content from webpages and import into Roam.

PDF extraction

Parse and extract text from PDF documents into Roam.

Transcript retrieval

Retrieve YouTube video transcripts and add to Roam.

Content type detection

Detect and process content types to apply appropriate parsing.