Skip to main content
Glama
Roam Research MCP Server

Roam Research MCP Server

by mickm3n

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

Related MCP server: MCP Memory Server

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
  1. Install dependencies:

uv sync
  1. 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

Available Tools

4 tools
get_page_contentA

Get the complete content of a specific page in Roam Research with all nested child blocks.

Retrieves all blocks on the specified page with their hierarchical structure,
including nested children up to 5 levels deep. Returns content in markdown format
with proper indentation to reflect the block hierarchy.

Args:
    page_name: Exact name of the page to retrieve (case-sensitive)
    
Returns:
    JSON string containing:
    - result: Array of blocks with content and timestamps
    - Each block includes: content (markdown), timestamp (edit time)
    
Examples:
    get_page_content("Daily Notes")
    get_page_content("Project Planning")
    get_page_content("信用卡")

Inputs: page_name (required). Returns: result

get_page_referencesA

Get all blocks that reference a specific page in Roam Research with pagination support.

Finds all blocks across your Roam database that contain links to the specified page.
Results are sorted by most recent edit time and include the full hierarchical context
of each referencing block.

Args:
    page_name: Exact name of the page to find references for (case-sensitive)
    limit: Maximum number of references to return per request (default: 10)
    cursor: Timestamp cursor for pagination - use next_cursor from previous response
           to get additional results
           
Returns:
    JSON string containing:
    - result: Array of referencing blocks with content and timestamps  
    - next_cursor: Timestamp for pagination (if more results available)
    - total_matches: Number of references found in this batch
    
Examples:
    get_page_references("GTD")
    get_page_references("Project Alpha", limit=20)
    get_page_references("Meeting Notes", limit=5, cursor=1640995200000)

Inputs: page_name (required), limit, cursor. Returns: result

write_to_pageA

Write hierarchical markdown content to a specific page in Roam Research.

Creates a new block structure on the specified page with automatic indentation
detection. Supports nested bullet points and maintains proper parent-child
relationships between blocks. Content is appended to the end of the page.

Args:
    page_name: Exact name of the target page (case-sensitive, must exist)
    content: Hierarchical markdown content using '- ' prefix and indentation
            Format: "- Main topic
- Subtopic
    - Details"
            Supports any indentation level with automatic detection
            
Returns:
    JSON string containing:
    - result: "success" if completed
    - blocks_created: Total number of blocks created (including children)
    - details: Array of individual block creation results
    
Examples:
    write_to_page("Project Notes", "- New milestone
- Task 1
- Task 2")
    write_to_page("信用卡", "- [[銀行/國泰]]
- 現金回饋 2%")

Inputs: page_name (required), content (required). Returns: result

write_to_todayA

Write hierarchical markdown content to today's daily page in Roam Research.

Automatically creates today's daily page if it doesn't exist, then adds the
provided content as a hierarchical block structure. Uses Roam's standard
date format (e.g., "July 28, 2025") and maintains proper block relationships.

Args:
    content: Hierarchical markdown content using '- ' prefix and indentation
            Format: "- Main topic
- Subtopic
    - Details"
            Supports any indentation level with automatic detection
            
Returns:
    JSON string containing:
    - result: "success" if completed
    - blocks_created: Total number of blocks created (including children) 
    - details: Array of individual block creation results
    
Examples:
    write_to_today("- Daily standup
- Completed: Bug fixes
- Next: Feature review")
    write_to_today("- [[會議/週會]]
- 參與者: @John, @Mary
- 議題: Q4 規劃")

Inputs: content (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: get_page_content retrieves page content, get_page_references finds references to pages, write_to_page writes to a specific page, and write_to_today writes to today's daily page. The separation between general page operations and the specialized daily page operation is well-defined, preventing confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case: get_page_content, get_page_references, write_to_page, and write_to_today. The naming is predictable and readable, making it easy for agents to understand the action and target at a glance.

    Tool Count4/5

    Four tools are reasonable for a Roam Research server, covering core read and write operations. However, the scope feels slightly thin as it lacks update or delete capabilities for existing blocks, which are common in note-taking workflows. The count is appropriate but could be more comprehensive.

    Completeness3/5

    The tools cover basic retrieval and creation for pages and daily notes, but there are notable gaps. Missing operations include updating or deleting existing blocks, searching across pages, and managing page metadata. This limits agents to read and append-only workflows, which may cause failures in more complex tasks.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server for Claude Desktop that provides structured memory management across chat sessions, allowing Claude to maintain context and build a knowledge base within project directories.
      11 npm
      7
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      MCP server for Roam Research that enables AI assistants like Claude and Cursor to read, write, search, and query your Roam graph with full write access.
      62
      -