Roam Research MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to Roam Research's API functionality. This server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface. It supports both standard input/output (stdio) and HTTP Stream communication. (A WORK-IN-PROGRESS, personal project not officially endorsed by Roam Research)

Installation and Usage

This MCP server supports two primary communication methods:

Stdio (Standard Input/Output): Ideal for local inter-process communication, command-line tools, and direct integration with applications running on the same machine. This is the default communication method when running the server directly.
HTTP Stream: Provides network-based communication, suitable for web-based clients, remote applications, or scenarios requiring real-time updates over HTTP. The HTTP Stream endpoint runs on port 8088 by default.

Running with Stdio

You can install the package globally and run it:

npm install -g roam-research-mcp
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
npm start

Running with HTTP Stream

To run the server with HTTP Stream support, you can either:

Use the default port: Run npm start after building (as shown above). The server will automatically listen on port 8088.
Specify a custom port: Set the HTTP_STREAM_PORT environment variable before starting the server.
```
HTTP_STREAM_PORT=9000 npm start
```
Or, if using a .env file, add HTTP_STREAM_PORT=9000 to it.

Docker

This project can be easily containerized using Docker. A Dockerfile is provided at the root of the repository.

Build the Docker Image

To build the Docker image, navigate to the project root and run:

docker build -t roam-research-mcp .

Run the Docker Container

To run the Docker container and map the necessary ports, you must also provide the required environment variables. Use the -e flag to pass ROAM_API_TOKEN, ROAM_GRAPH_NAME, and optionally MEMORIES_TAG and HTTP_STREAM_PORT:

docker run -p 3000:3000 -p 8088:8088 \
  -e ROAM_API_TOKEN="your-api-token" \
  -e ROAM_GRAPH_NAME="your-graph-name" \
  -e MEMORIES_TAG="#[[LLM/Memories]]" \
  -e HTTP_STREAM_PORT="8088" \
  roam-research-mcp

Alternatively, if you have a .env file in the project root (which is copied into the Docker image during build), you can use the --env-file flag:

docker run -p 3000:3000 -p 8088:8088 --env-file .env roam-research-mcp

To Test

Run MCP Inspector after build using the provided npm script:

npm run inspector

Features

The server provides powerful tools for interacting with Roam Research:

Environment variable handling with .env support
Comprehensive 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

roam_fetch_page_by_title: Fetch page content by title.
roam_create_page: Create new pages with optional content and headings.
roam_create_block: Add new blocks to an existing page or today's daily note.
roam_import_markdown: Import nested markdown content under a specific block.
roam_add_todo: Add a list of todo items to today's daily page.
roam_create_outline: Add a structured outline to an existing page or block.
roam_search_block_refs: Search for block references within a page or across the entire graph.
roam_search_hierarchy: Search for parent or child blocks in the block hierarchy.
roam_find_pages_modified_today: Find pages that have been modified today (since midnight).
roam_search_by_text: Search for blocks containing specific text.
roam_update_block: Update a single block identified by its UID.
roam_update_multiple_blocks: Efficiently update multiple blocks in a single batch operation.
roam_search_by_status: Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.
roam_search_by_date: Search for blocks or pages based on creation or modification dates.
roam_search_for_tag: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby.
roam_remember: Add a memory or piece of information to remember.
roam_recall: Retrieve all stored memories.
roam_datomic_query: Execute a custom Datomic query on the Roam graph beyond the available search tools.

Setup

Create a Roam Research API token:
- Go to your graph settings
- Navigate to the "API tokens" section (Settings > "Graph" tab > "API Tokens" section and click on the "+ New API Token" button)
- Create a new token
Configure the environment variables: You have two options for configuring the required environment variables:

Option 1: Using a .env file (Recommended for development) Create a .env file in the roam-research directory:
```
ROAM_API_TOKEN=your-api-token
ROAM_GRAPH_NAME=your-graph-name
MEMORIES_TAG='#[[LLM/Memories]]'
HTTP_STREAM_PORT=8088 # Or your desired port for HTTP Stream communication
```
Option 2: Using MCP settings (Alternative method) Add the configuration to your MCP settings file. Note that you may need to update the args to ["/path/to/roam-research-mcp/build/index.js"] if you are running the server directly.
- For Cline (~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):
- For Claude desktop app (~/Library/Application Support/Claude/claude_desktop_config.json):
```
{
  "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]]",
        "HTTP_STREAM_PORT": "8088"
      }
    }
  }
}
```
Note: The server will first try to load from .env file, then fall back to environment variables from MCP settings.
Build the server (make sure you're in the root directory of the MCP):
```
cd roam-research-mcp
npm install
npm run build
```

Error Handling

The server provides comprehensive error handling for common scenarios:

Configuration errors:
- Missing API token or graph name
- Invalid environment variables
API errors:
- Authentication failures
- Invalid requests
- Failed operations
Tool-specific errors:
- Page not found (with case-insensitive search)
- Block not found by string match
- Invalid markdown format
- Missing required parameters
- Invalid outline structure or content

Each error response includes:

Standard MCP error code
Detailed error message
Suggestions for resolution when applicable

Development

Building

To build the server:

npm install
npm run build

This will:

Install all required dependencies
Compile TypeScript to JavaScript
Make the output file executable

You can also use npm run watch during development to automatically recompile when files change.

Testing with MCP Inspector

The MCP Inspector is a tool that helps test and debug MCP servers. To test the server:

# Inspect with npx:
npx @modelcontextprotocol/inspector node build/index.js