MCP HubMCP Hub
2b3pro

roam-research-mcp

by: 2b3pro

MCP Server for Roam Research Graph Integration

34created 19/12/2024
Visit
Roam
Integration

📌Overview

Purpose: To provide a standardized Model Context Protocol (MCP) server that enables AI assistants to interact with Roam Research's API functionalities.

Overview: The Roam Research MCP Server is a work-in-progress project that facilitates comprehensive access to Roam Research's API. It allows the integration of AI tools into the Roam ecosystem, enabling various operations on Roam graphs through a set of powerful APIs.

Key Features:

  • Environment Variable Management: Supports .env files for easy configuration of API tokens and graph details, promoting seamless integration and setup.

  • Extensive API Functionality: Offers an array of operations such as creating pages and blocks, searching for text or tags, updating content, and executing complex queries, enhancing the interaction experience with Roam graphs.

  • Error Handling: Includes robust error management to handle configuration and API errors effectively, ensuring users receive clear feedback and suggestions for resolution.

  • Hierarchical Structure Support: Facilitates the creation of outlines and block hierarchies, maintaining proper relationships and enabling organized content management.

Roam Research MCP Server

A Model Context Protocol (MCP) server that provides access to Roam Research's API functionality. It enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface. (Work-in-progress, personal project not officially endorsed by Roam Research)

Installation

Install the package globally:

npm install -g roam-research-mcp

Or 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

Features

The server provides tools such as:

  • Environment variable handling with .env support
  • Input validation
  • Case-insensitive page title matching
  • Recursive block reference resolution
  • Markdown parsing and conversion
  • Daily page integration
  • Detailed debug logging
  • Efficient batch operations
  • Hierarchical outline creation

Key tools include:

  1. Fetch page content by title with recursive block resolution
  2. Create new pages and blocks
  3. Import nested markdown into pages/blocks
  4. Add todo items to today's daily page
  5. Create hierarchical outlines
  6. Search block references and by text
  7. Update block content, including pattern-based transformations
  8. Search for blocks by tags, date, or hierarchy
  9. Remember and recall information with tagging
  10. Execute custom Datalog queries on the graph
  11. Find pages modified today

Setup

  1. Create a Roam Research API token:

    • In your Roam graph settings: Settings > Graph tab > API Tokens > + New API Token

  2. Configure environment variables:

Option 1: .env file (recommended):

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

Option 2: MCP settings file (e.g. for Cline or Claude desktop):

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

The server prefers .env settings but falls back to MCP environment variables.

  1. Build the server:
cd roam-research-mcp
npm install
npm run build

Usage Examples

Fetch Page By Title

Fetch a page's content recursively with block references resolved (up to 4 levels):

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

Returns the page content as markdown with hierarchical nesting and full formatting.

Create Page

Create a new page with optional content:

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

Returns the created page's UID on success.

Create Block

Add a new block to a page or today's daily page (if no page specified):

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

Returns success status, new block UID, and parent UID.

Create Outline

Create a hierarchical outline with nesting levels:

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

Supports up to 10 nesting levels; defaults to today's page if unspecified.

Returns success with created block UIDs.

Add Todo Items

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

Todos use Roam checkbox syntax and are added as top-level blocks.

Import Nested Markdown

Import nested markdown under a specific block or page:

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

Defaults to today's page if no page specified. Can add content as first or last child.

Returns success with created UIDs.

Search Block References

Find block references by block UID or within a page:

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

Returns blocks containing references with context.

Search By Text

Search blocks for 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
}

Supports global or page-scoped and case-sensitive or insensitive search.

Update Block Content

Update a block's content directly or via regex pattern:

Direct replacement:

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

Pattern-based transform:

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

Returns updated content on success.

Search For Tags

Find blocks with specific tags, optionally near other 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
}

Returns matching blocks with their page context.

Remember Information

Store information tagged as memories:

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

Tags the memory with #[[LLM/Memories]] and optional categories on today's page.

Search By Date

Search blocks or pages by creation/modification date:

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
}

Filters by date range, type, and scope.

Find Pages Modified Today

List pages modified since midnight today:

use_mcp_tool roam-research roam_find_pages_modified_today {}

Returns unique modified page titles and count.

Execute Datomic Queries

Run 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": []
}

Supports complex queries, aggregation, string ops, logical ops, and recursive rules.

Example: Count pages

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

Search Block Hierarchy

Search parent-child block 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
}

Retrieve blocks up or down the hierarchy with depth info.

Error Handling

The server handles errors such as:

  • Missing or invalid API tokens and environment variables
  • Authentication and API request failures
  • Tool-specific errors like page/block not found, invalid markdown, missing parameters, or invalid outlines

Error responses include standard MCP error codes, detailed messages, and suggestions when applicable.

Development

Building

To build the server:

npm install
npm run build

Installs dependencies, compiles TypeScript, and creates executable output.

Use npm run watch for auto-recompiling during development.

Testing with MCP Inspector

Test and debug the server using the MCP Inspector tool:

npx @modelcontextprotocol/inspector node build/index.js

This launches an interactive interface to list and execute available tools and inspect responses.

License

MIT License