📌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 for comprehensive access to Roam Research's API functionality. This server enables AI assistants to interact with your Roam Research graph through a standardized interface. (A work in progress, personal project not officially endorsed by Roam Research)

Installation

You can 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

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

Available Functions

roam_fetch_page_by_title: Fetch a page's content by title.
roam_create_page: Create new pages with optional content.
roam_create_block: Create new blocks in a page.
roam_import_markdown: Import nested markdown content.
roam_add_todo: Add multiple todo items to the daily page.
roam_create_outline: Create hierarchical outlines.
roam_search_block_refs: Search for block references.
roam_find_pages_modified_today: Find all pages modified today.
roam_search_by_text: Search for blocks by specific text.
roam_update_block: Update block content with transformations.
roam_search_for_tag: Search for blocks with specific tags.
roam_remember: Store memories with automatic tagging.
roam_search_by_date: Search based on creation or modification dates.
roam_datomic_query: Execute custom Datalog queries.

Setup

Create a Roam Research API token:
- Go to your graph settings.
- Create a new token in the "API tokens" section.
Configure the environment variables:
- You can use a .env file or add settings to your MCP settings file.

Build the server:

cd roam-research-mcp
npm install
npm run build

Usage Examples

Fetch Page By Title

Fetch and read a page's content:

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

Create Page

Create a new page:

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

Create Block

Add a new block to a page:

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

Search Behavior

Search for blocks by text:

use_mcp_tool roam-research roam_search_by_text {
  "text": "search text",
  "page_title_uid": "optional-page-title-or-uid"
}

Error Handling

The server provides comprehensive error handling for common scenarios, including configuration errors, API errors, and tool-specific errors.

Development

Building

To build the server:

npm install
npm run build

Testing with MCP Inspector

To test the server:

npx @modelcontextprotocol/inspector node build/index.js

License

MIT License