Roam MCP

Roam MCP and CLI

The official Model Context Protocol (MCP) server and CLI for Roam Research. Connect Claude, Cursor, and other AI assistants to your Roam graph — read, write, search, and query.

Alpha Software: This project is in early development and subject to breaking changes.

[!CAUTION] Full Write Access: This MCP server gives Claude full read and write access to your Roam graph. Claude can create, modify, and delete pages and blocks. Changes may be difficult or impossible to undo. Roam does not have a traditional undo history that can reverse bulk operations or deletions made through the API.

Recommendations:

• Back up your graph before use
• Start with a test graph to understand Claude's behavior
• Review what Claude plans to do before confirming write operations
• Be specific in your instructions to avoid unintended changes

Prerequisites

• Node.js v18 or later
• Roam Research desktop app (the local API is not available in the web version)

How It Works

This MCP server connects to Roam's local HTTP API, which runs on your machine when the desktop app is open. If Roam isn't running when a tool is called, the server will automatically launch it via deep link and retry the connection.

Getting Started

1. Roam Desktop App

The local API requires the Roam desktop app (not the web version). Make sure it's installed and you can open your graph in it.

2. Connect a Graph

Interactive (recommended for first-time setup):

npx @roam-research/roam-mcp connect

This will walk you through selecting a graph, choosing permissions, and approving the token in Roam. You can also use the CLI: install globally with npm install -g @roam-research/roam-cli, then use roam connect.

Non-interactive (for scripts and LLM agents):

# example to connect to your graph called "my-graph-name" which you generally refer to as "My Team Graph"
npx @roam-research/roam-mcp connect --graph my-graph-name --nickname "My Team Graph" --access-level full

# example to connect to a public graph - our "help" graph
npx @roam-research/roam-mcp connect --graph help --public --nickname "Roam official help graph"

Note: Both modes require a human to approve the token dialog in the Roam desktop app.

To remove a connection:

npx @roam-research/roam-mcp connect --remove --graph my-graph-name
npx @roam-research/roam-mcp connect --remove --nickname "My Team Graph"

Run connect again to add more graphs or update permissions.

3. Connect to an MCP Client

Claude Desktop

Add to your Claude Desktop config file:

{
  "mcpServers": {
    "roam": {
      "command": "npx",
      "args": ["-y", "@roam-research/roam-mcp"]
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop after saving.

Claude Code

claude mcp add -s user roam-mcp -- npx -y @roam-research/roam-mcp

This makes Roam available in all your Claude Code sessions. To add it to a single project only, use -s local instead.

Multiple Graphs

Run connect multiple times to add additional graphs. Each graph gets a nickname (a short name like "work" or "team acme") for easy selection.

Graph Selection:

• Single graph configured: Auto-selected, no action needed
• Multiple graphs configured: Pass the graph parameter on each tool call with the nickname

Manual Configuration (Advanced)

Instead of using connect, you can manually create ~/.roam-tools.json:

{
  "version": 1,
  "graphs": [
    {
      "name": "your-graph-name",
      "type": "hosted",
      "token": "roam-graph-local-token-...",
      "nickname": "my-graph"
    }
  ]
}

To create a token manually: Roam Desktop → Settings → Graph → Local API Tokens → New Token.

accessLevel records what the token was granted; it is not enforced by the CLI or MCP server — Roam enforces the token's real permissions. Setting it by hand does not change what an agent can do. (A fourth value, "read-edit-own", is accepted by the config schema, and whatever level Roam grants is written to your config verbatim. Roam's local API does not currently grant that tier, so you are unlikely to see it in a locally-created token.)

Available Tools

Graph Management:

• list_graphs - List all configured graphs with their nicknames
• setup_new_graph - Set up a new graph connection, or list available graphs

Graph Guidelines:

• get_graph_guidelines - Returns user-defined instructions and preferences for AI agents

Graph guidelines let you store preferences and context directly in your Roam graph that AI agents will follow. Create a page called [[roam/agent guidelines]] with your instructions. These might include naming conventions, preferred page structures, topics to focus on, or any other context that should guide how the AI interacts with your graph.

Content:

• create_page - Create page with markdown content
• update_page - Update page title or children view type
• delete_page - Delete a page (errors with NOT_FOUND when nothing exists to delete; older Roam servers may instead report success without deleting)
• create_block - Create blocks (by parent UID, page title, or daily note date — MM-DD-YYYY or today/yesterday/tomorrow; with optional nest-under)
• append_to_daily_note - Append/capture markdown to a daily note (today by default, or MM-DD-YYYY / today/yesterday/tomorrow; optional nest-under section)
• update_block - Update block content/properties
• move_block - Move a block to a new location
• delete_block - Delete a block (errors with NOT_FOUND when nothing exists to delete; older Roam servers may instead report success without deleting)
• add_comment - Add a comment to a block (comment thread, not child block)
• get_comments - Get comments on a block with author/date context

Read:

• search - Search pages/blocks (empty query returns recently edited/viewed content)
• semantic_search - Semantic (embeddings) search by meaning; requires embeddings enabled and a signed-in user
• suggest_links - Suggest existing pages worth linking to from a passage of text (does not create links)
• search_templates - Search Roam templates by name
• roam_query - Execute a Roam query ({{query:}} blocks, not Datalog)
• datalog_query - Execute a raw Datalog query against the graph's Datomic database
• get_page - Get page content as markdown
• get_block - Get block content as markdown
• get_backlinks - Get references to a page/block

Navigation:

• get_open_windows - Main window view and all sidebar windows
• get_selection - Currently focused block and multi-selected blocks
• open_main_window - Navigate to page/block
• open_sidebar - Open in right sidebar

Shortcuts:

• add_shortcut - Add a page to the left sidebar Shortcuts / starred pages (optional index to position it)
• remove_shortcut - Remove a page from the left sidebar Shortcuts / starred pages

Files:

• file_get - Fetch a file hosted on Roam (handles decryption for encrypted graphs)
• file_upload - Upload a file to Roam (from local path, URL, or base64)
• file_delete - Delete a file hosted on Roam

Developer:

• reload_dev_extensions - Reload all developer-mode extensions in Roam Desktop (apply code changes without restarting)
• call_extension_tool - Invoke an AI tool registered by a Roam extension or roam/js script (discover available tools via the extensionTools field of get_graph_guidelines)

Hiding content from the AI

Blocks tagged #.rm-hide or #.rm-private — and everything nested under them — are omitted from the content these tools return. The read tools that surface graph content to the AI (get_page, get_block, get_backlinks, search, semantic_search, roam_query) all skip hidden subtrees. (search_templates is the exception: template previews are NOT filtered, so hidden blocks inside a shared template can appear in its results.) Both the hashtag (#.rm-hide) and link ([[.rm-hide]]) forms work; .rm-private is Roam's existing "hidden from other users" tag, while .rm-hide hides from the AI specifically.

This is a convenience filter, not a security guarantee. The filtering is applied only to the AI content tools above. The raw datalog_query tool reads the database directly and does not apply it, so a capable agent could still surface hidden blocks through datalog. Don't rely on these tags for anything truly sensitive — treat them as "keep it out of the AI's way," not "keep it secret."

Agent skill: roam-syntax

The skills/roam-syntax/ directory contains an Agent Skill that teaches AI agents Roam's syntax and the MCP read/write model: Roam-flavored markdown (it differs from standard markdown — e.g. italics are __text__), how to read the <roam .../>-tagged output the read tools return, and how to write content back without corrupting block references. Agents connected through this MCP server get a compact version of the same guidance automatically (the roamSyntax field of get_graph_guidelines plus the tool descriptions); the skill adds depth — full syntax, {{...}} components, queries, and worked read→edit→write examples — for agent platforms that support skills (Claude Code, Claude.ai, Codex, …). To use it, copy skills/roam-syntax/ into your agent's skills directory (e.g. .claude/skills/).

CLI

Install globally for quick access:

npm install -g @roam-research/roam-cli

roam list-graphs
roam connect                                                    # Interactive setup
roam connect --graph <name> --nickname <name>                   # Non-interactive
roam search --query "my notes" --graph <name-or-nickname>
roam get-page --title "My Page" --graph <name-or-nickname>

If you only have one graph configured, the --graph flag is optional.

Run roam --help to see all available commands. You can also use npx @roam-research/roam-cli without installing globally.

Packages

This repository is a monorepo with four packages:

See CHANGELOG.md for release history.

Development

To work on this project from source:

git clone https://github.com/Roam-Research/roam-tools.git
cd roam-tools
npm install
npm run build

Development commands:

npm run mcp              # Run MCP server in dev mode (tsx)
npm run cli -- connect   # Run CLI in dev mode
npm run typecheck        # Type-check (force rebuild, checks all packages)
npm run lint             # Lint with ESLint
npm run format:check     # Check formatting with Prettier
npm run version:check    # Verify all package versions are consistent
npm run version:bump 0.5.0  # Bump all packages to a new version

See architecture for how the four packages divide responsibility and the core contract external consumers depend on, and npm packaging design for why the packages are structured this way.

Contributing

This project is changing rapidly. At this time, we prefer suggestions and feedback over pull requests. Please open an issue or join the #ai-in-roam channel on slack to discuss ideas before submitting code.