What can you do with this server?

The Roam Research MCP server enables AI assistants to programmatically interact with Roam Research graphs through a standardized interface, providing comprehensive read and write operations: * Content retrieval: Fetch pages by title, search for specific text, dates, block references, or pages modified today * Content creation: Create new pages, blocks, hierarchical outlines, or import markdown * Content management: Add todos, update blocks (individually or in batch), store and recall memories * Advanced search: Search by tags, status (TODO/DONE), hierarchy, or execute custom Datomic/Datalog queries * Automation: Perform batch operations and efficiently handle nested content structures This allows AI assistants to fully leverage Roam's database capabilities for both retrieving and manipulating graph content.

Which integrations are available for this server?

Supports loading configuration from .env files for managing environment variables like API tokens and graph names. Enables parsing and conversion of markdown content, with support for importing nested markdown structures into Roam Research with proper hierarchy preservation. Provides comprehensive access to Roam Research's API functionality, allowing AI assistants to interact with Roam Research graphs through tools for fetching, creating, and updating pages and blocks, importing markdown, searching content, and executing Datalog queries.

How do I use Roam Research?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Roam Research search for notes about project planning from last month" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Roam Research by 2b3pro

Roam Research MCP + CLI

npm version Project Status: Active License: MIT GitHub

Introduction

I created this project to solve a personal problem: I wanted to manage my Roam Research graph directly from Claude Code (and other LLMs). As I built the Model Context Protocol (MCP) server to give AI agents access to my notes, I realized the underlying tools were powerful enough to stand on their own.

What started as an backend for AI agents evolved into a full-featured Standalone CLI. Now, you can use the same powerful API capabilities directly from your terminal—piping content into Roam, searching your graph, and managing tasks—without needing an LLM at all.

Whether you want to give Claude superpowers over your knowledge base or just want a robust CLI for your own scripts, this project has you covered.

Related MCP server: Shared Knowledge MCP Server

Standalone CLI: `roam`

The roam CLI lets you interact with your graph directly from the terminal. It supports standard input (stdin) piping for all content creation and retrieval commands, making it perfect for automation workflows.

Quick Examples

# Save a quick thought to your daily page roam save "Idea: A CLI for Roam would be cool" # Pipe content from a file to a new page cat meeting_notes.md | roam save --title "Meeting: Project Alpha" # Create a TODO item on today's daily page echo "Buy milk" | roam save --todo # Search your graph and pipe results to another tool roam search "important" --json | jq . # Search for pages by namespace prefix roam search --namespace "Convention" # Finds all Convention/* pages # Fetch a page by title roam get "Roam Research" # Fetch page by UID or Roam URL roam get page abc123def roam get page "https://roamresearch.com/#/app/my-graph/page/abc123def" # Sort and group results roam get --tag Project --sort created --group-by tag # Find references (backlinks) to a page roam refs "Project Alpha" # Update a block (e.g., toggle TODO status) roam update ((block-uid)) --todo # Multi-graph: read from a specific graph roam get "Page Title" -g work # Multi-graph: write to a protected graph roam save "Note" -g work --write-key "$ROAM_SYSTEM_WRITE_KEY"

Available Commands: get, search, save, refs, update, batch, rename, status. Run roam <command> --help for details on any command.

Installation

npm install -g roam-research-mcp # The 'roam' command is now available globally

MCP Server Tools

The MCP server exposes these tools to AI assistants (like Claude), enabling them to read, write, and organize your Roam graph intelligently.

Multi-Graph Support: All tools accept optional graph and write_key parameters. Use graph to target a specific graph from your ROAM_GRAPHS config, and write_key for write operations on protected graphs.

Tool Name	Description
`roam_fetch_page_by_title`	Fetch page content by title.
`roam_fetch_block_with_children`	Fetch a block and its nested children by UID (resolves refs).
`roam_create_page`	Create new pages, optionally with mixed text and table content.
`roam_update_page_markdown`	Update a page using smart diff (preserves block UIDs).
`roam_search_by_text`	Full-text search across the graph or within specific pages. Supports namespace prefix search for page titles.
`roam_search_block_refs`	Find blocks that reference a page, tag, or block UID.
`roam_search_by_status`	Find TODO or DONE items.
`roam_search_for_tag`	Find blocks containing specific tags (supports exclusion).
`roam_search_by_date`	Find blocks/pages by creation or modification date.
`roam_find_pages_modified_today`	List pages modified since midnight.
`roam_add_todo`	Add TODO items to today's daily page.
`roam_create_table`	Create properly formatted Roam tables.
`roam_create_outline`	Create hierarchical outlines.
`roam_process_batch_actions`	Execute multiple low-level actions (create, move, update, delete) in one batch.
`roam_move_block`	Move a block to a new parent or position.
`roam_remember` / `roam_recall`	specialized tools for AI memory management within Roam.
`roam_datomic_query`	Execute raw Datalog queries for advanced filtering.
`roam_markdown_cheatsheet`	Retrieve the Roam-flavored markdown reference.

Configuration

Environment Variables

Single Graph Mode

For a single Roam graph, set these in your environment or a .env file:

ROAM_API_TOKEN=your-api-token ROAM_GRAPH_NAME=your-graph-name

Multi-Graph Mode (v2.0+)

Connect to multiple Roam graphs from a single server instance:

ROAM_GRAPHS='{ "personal": {"token": "token-1", "graph": "personal-db", "memoriesTag": "#[[Personal Memories]]"}, "work": {"token": "token-2", "graph": "work-db", "protected": true, "memoriesTag": "#[[Work Memories]]"}, "research": {"token": "token-3", "graph": "research-db"} }' ROAM_DEFAULT_GRAPH=personal ROAM_SYSTEM_WRITE_KEY=your-secret-key

Graph Configuration Options:

Property	Required	Description
`token`	Yes	Roam API token for this graph
`graph`	Yes	Graph name/database identifier
`protected`	No	If `true`, writes require `ROAM_SYSTEM_WRITE_KEY` confirmation
`memoriesTag`	No	Tag for `roam_remember`/`roam_recall` (overrides global default)

Write Protection: Protected graphs require the write_key parameter matching ROAM_SYSTEM_WRITE_KEY for any write operation. This prevents accidental writes to sensitive graphs.

Optional:

ROAM_MEMORIES_TAG: Default tag for roam_remember/roam_recall (fallback when per-graph memoriesTag not set).
HTTP_STREAM_PORT: To enable HTTP Stream (defaults to 8088).

Running the Server

1. Stdio Mode (Default) Best for local integration (e.g., Claude Desktop, IDE extensions).

npx roam-research-mcp

2. HTTP Stream Mode Best for remote access or web clients.

HTTP_STREAM_PORT=8088 npx roam-research-mcp

3. Docker

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

Configuring in LLMs

Claude Desktop / Cline:

Add to your MCP settings file (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json):

Single Graph:

{ "mcpServers": { "roam-research": { "command": "npx", "args": ["-y", "roam-research-mcp"], "env": { "ROAM_API_TOKEN": "your-token", "ROAM_GRAPH_NAME": "your-graph" } } } }

Multi-Graph:

{ "mcpServers": { "roam-research": { "command": "npx", "args": ["-y", "roam-research-mcp"], "env": { "ROAM_GRAPHS": "{\"personal\":{\"token\":\"token-1\",\"graph\":\"personal-db\",\"memoriesTag\":\"#[[Memories]]\"},\"work\":{\"token\":\"token-2\",\"graph\":\"work-db\",\"protected\":true}}", "ROAM_DEFAULT_GRAPH": "personal", "ROAM_SYSTEM_WRITE_KEY": "your-secret-key" } } } }

Query Block Parser (v2.11.0+)

A utility for parsing and executing Roam query blocks programmatically. Converts {{[[query]]: ...}} syntax into Datalog queries.

Supported Clauses

Clause	Syntax	Description
Page ref	`[[page]]`	Blocks referencing a page
Block ref	`((uid))`	Blocks referencing a block
`and`	`{and: [[a]] [[b]]}`	All conditions must match
`or`	`{or: [[a]] [[b]]}`	Any condition matches
`not`	`{not: [[tag]]}`	Exclude matches
`between`	`{between: [[date1]] [[date2]]}`	Date range filter
`search`	`{search: text}`	Full-text search
`daily notes`	`{daily notes: }`	Daily notes pages only
`by`	`{by: [[User]]}`	Created or edited by user
`created by`	`{created by: [[User]]}`	Created by user
`edited by`	`{edited by: User}`	Edited by user

Relative Dates

The between clause supports relative dates: today, yesterday, last week, last month, this year, 7 days ago, 2 months ago, etc.

Usage

import { QueryExecutor } from 'roam-research-mcp/query'; const executor = new QueryExecutor(graph); // Execute a query const results = await executor.execute( '{{[[query]]: "My Query" {and: [[Project]] {between: [[last month]] [[today]]}}}}' ); // Parse without executing (for debugging) const { name, query } = QueryParser.parseWithName(queryBlock);

Utility Functions

import { isQueryBlock, extractQueryBlocks } from 'roam-research-mcp/query'; // Detect if text is a query block isQueryBlock('{{[[query]]: [[tag]]}}'); // true // Extract all query blocks from a string extractQueryBlocks(pageContent); // ['{{[[query]]: ...}}', ...]

Support

If this project helps you manage your knowledge base or build cool agents, consider buying me a coffee! It helps keep the updates coming.

https://paypal.me/2b3/5

License

MIT License - Created by Ian Shen.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

Resources

Need Help?

Report Issue

Related Servers

Tools

View all tools

Roam Research

Roam Research MCP + CLI

Introduction

Standalone CLI: `roam`

Quick Examples

Installation

MCP Server Tools

Configuration

Environment Variables

Single Graph Mode

Multi-Graph Mode (v2.0+)

Running the Server

Configuring in LLMs

Query Block Parser (v2.11.0+)

Supported Clauses

Relative Dates

Usage

Utility Functions

Support

License

Resources

Tools

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

Roam Research MCP + CLI

Introduction

Standalone CLI: roam

Quick Examples

Installation

MCP Server Tools

Configuration

Environment Variables

Single Graph Mode

Multi-Graph Mode (v2.0+)

Running the Server

Configuring in LLMs

Query Block Parser (v2.11.0+)

Supported Clauses

Relative Dates

Usage

Utility Functions

Support

License

Resources

Tools

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

Standalone CLI: `roam`