Roam Research MCP Server

A Model Context Protocol (MCP) server that provides tools to interact with Roam Research API, enabling Claude Desktop to read from and write to your Roam Research graph.

Features

• Get Page Content: Retrieve content from any page with nested child blocks in markdown format
• Get Page References: Find all references to a specific page with pagination support and time-based sorting
• Write to Page: Add new blocks to existing pages
• Write to Today: Add content to today's daily page (auto-creates if needed)
• Markdown Conversion: Automatically converts Roam-style [[links]] to markdown format
• Nested Block Support: Handles hierarchical block structures with proper indentation

Installation

Prerequisites

• Python 3.11+
• uv package manager
• Roam Research API token and graph access

Setup

1. Clone the repository:

git clone <repository-url>
cd roam-research-mcp

2. Install dependencies:

uv sync

3. Set up environment variables:

export ROAM_TOKEN="your_roam_research_api_token"
export ROAM_GRAPH_NAME="your_graph_name"

Claude Desktop Integration

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "roam-research": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/roam-research-mcp",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "ROAM_TOKEN": "your_actual_roam_token",
        "ROAM_GRAPH_NAME": "your_graph_name"
      }
    }
  }
}

Usage

Once configured with Claude Desktop, you can:

• Ask Claude to read content from your Roam pages
• Have Claude write notes and thoughts to your daily pages
• Query page references and connections
• Add structured content to specific pages

Development

See CLAUDE.md for development guidelines and git commit conventions.

API Requirements

• Valid Roam Research API token
• Graph name with API access enabled
• Network access to api.roamresearch.com

License

MIT License