Roam Research

You can run the Roam Research MCP Server locally to expose Roam Research API functionality through a standard MCP interface. It supports both local, stdio-based communication and networked HTTP Stream access, making it easy to connect AI assistants and other tools to your Roam graph.

How to use

You will run the MCP server in either stdio mode for local inter-process communication or HTTP Stream mode for networked access. In stdio mode, you start the server from your terminal and interact with it directly on your machine. In HTTP Stream mode, the server listens on a configurable port and exposes an HTTP-based stream that clients can connect to for real-time updates.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system.

Install the MCP server globally and run it directly from your shell, or clone the project and build from source.

Install globally and run:

npm install -g roam-research-mcp
roam-research-mcp

Or clone the repository, build, and start the server from source:

git clone https://github.com/2b3pro/roam-research-mcp.git
cd roam-research-mcp
npm install
npm run build
npm start

Configuration and usage notes

HTTP Stream access is available by default on port 8088 when you use the standard start flow that builds the server. You can customize the port by setting HTTP_STREAM_PORT before starting the server, for example via an environment variable.

Environment variables you may configure include API token and graph details, plus optional memory tagging and a custom instructions file. These variables are loaded from a .env file or from your MCP settings if you are integrating with a client application.

Deployment options (Docker)

You can containerize the server with Docker. Provide required environment variables when you run the container to supply API credentials and graph details.

Standalone tools

In addition to the MCP server, you can use a standalone tool to import Markdown content directly into Roam Research. This tool reads Markdown from stdin and creates or updates Roam pages accordingly.

Tool overview

The server exposes a collection of tools that enable interactions with Roam data, such as fetching pages by title, creating pages, importing Markdown, manipulating blocks and outlines, and performing complex searches across the graph. Each tool is designed to be used from an MCP client and supports batch operations for complex edits.

Error handling and debugging

If something goes wrong, you’ll receive a structured error response that includes an error code, a message, and tips to resolve the issue. Typical problems include missing configuration values, authentication failures, or invalid requests. Detailed logs help you diagnose and fix issues quickly.

Development and testing

To develop or test locally, you can build the server, run it, and use the MCP Inspector tool to interact with available tools and verify responses. This helps you confirm correct behavior before integrating with your own clients.

Notes on usage patterns

For best results, identify Roam pages and blocks by their unique identifiers (UIDs) whenever possible to avoid ambiguity. When working with text, be mindful of case sensitivity in Roam content.

Available tools

roam_fetch_page_by_title

Fetch content for a page by its title and return the content in a specified format.

roam_fetch_block_with_children

Fetch a block by UID along with its hierarchical children down to a given depth, handling ((UID)) formatting.

roam_create_page

Create a new Roam page with optional content and headings, and link it from the current daily page.

roam_import_markdown

Import nested markdown content under a specific block, using batch actions for nesting.

roam_add_todo

Add a list of todo items to today's daily page through a batch operation.

roam_create_outline

Add a structured outline to an existing page or block, with support for children view types.

roam_search_block_refs

Search for block references within a page or across the graph.

roam_search_hierarchy

Search for parent or child blocks in the block hierarchy.

roam_find_pages_modified_today

Find pages modified since midnight with pagination and sorting.

roam_search_by_text

Search for blocks containing specific text, across all pages or within a specific page.

roam_search_by_status

Search blocks by status (TODO/DONE) across the graph or within a 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, with optional nearby tag filtering.

roam_remember

Store a memory or piece of information for recall later.

roam_recall

Retrieve all stored memories.

roam_datomic_query

Execute a custom Datomic query on the Roam graph with optional client-side regex filtering.

roam_markdown_cheatsheet

Provide the Roam Markdown Cheatsheet content, optionally concatenated with custom instructions.

roam_process_batch_actions

Execute a sequence of block actions (create, update, move, delete) in a single batch for complex nesting.