Roam Research MCP Server

What started as an backend for AI agents evolved into a full-featuredStandalone 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.

How this differs from Roam's official MCP server

Reach for the official server whenyou want Roam's own supported path, or you need things only the running app can do: controlling the Desktop UI (open a page, read the current selection, drive the sidebar), semantic/embeddings search, link suggestions, file upload, comments, or invoking tools that Roam extensions register.

Reach for this one whenRoam isn't running or isn't installed — a server, a container, a cron job, a CI step. Or when you want the extras this project has grown: a full standalone CLI with stdin piping, a shared HTTP daemon with optional bearer auth, smart page diffing that preserves block UIDs (and therefore your block references), batch operations with UID placeholders for building nested structures in one call, and agent memory tools.

One deliberate omission:there is no page-delete tool here.Roam has no undo that can reverse a bulk API deletion. The official server does offerdelete_page; this project takes the more conservative line.

The two servers share conventions on purpose, so running both costs you nothing:

TheroamCLI lets you interact with your graph directly from the terminal. It supportsstandard input (stdin) pipingfor all content creation and retrieval commands, making it perfect for automation workflows.

# 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 # Prepend to top of page (newest-first ordering) roam save -p "Changelog" --order first "v2.18.0 release" # 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 daily pages using any date format (auto-normalized) roam get today # Today's daily page roam get 2026-03-21 # ISO date → "March 21st, 2026" roam get "03/21/2026" # US date → "March 21st, 2026" roam get "March 21" # Named (assumes current year) # Fetch a block with ancestors (parent chain to page root) roam get abc123def -a # Block + children + ancestors roam get abc123def -a -d 0 # Ancestors only, no children # 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"

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

// roam_process_batch_actions { "success": true, "uid_map": { "parent1": "Xk7mN2pQ9" }, "validation_passed": true, "actions_attempted": 4 }

Before 3.1.0 this modealso*opened an HTTP listener, and bound it to every interface. If you were using that endpoint, run a--serverdaemon instead; see below.

2. Shared Server Mode (--server)Best for a single long-lived, HTTP-only daemon thatmultiple MCP clients share— instead of each session spawning its own subprocess. This saves memory and gives clients a stable URL.

HTTP_STREAM_PORT=8088 npx roam-research-mcp --server

Or manage it through theroamCLI, which adds start/stop/status/logs:

roam server start # start the shared daemon in the background roam server start -H 0.0.0.0 # expose on the LAN (no transport auth!) roam server status # is it up? version, graphs, active sessions roam server logs -f # follow the log roam server stop # stop a CLI-started daemon

roam server statusworks no matter how the daemon was launched (it probes/health), so it also reports a daemon started by a LaunchAgent/systemd unit. State (pidfile + log) lives in~/.roam/(override withROAM_HOME).

The two modes are mutually exclusive, and each opens exactly one transport: stdio mode speaks stdio and binds nothing,--serverspeaks HTTP and reads no stdin. In--servermode the server:

- runsHTTP-only(no stdio transport),
- binds theexactHTTP_STREAM_PORTonHTTP_STREAM_HOSTandexits non-zero if the port is taken(no silent drift — a shared daemon must keep a stable URL),
- exposesGET /health→{"status":"ok", ...}for liveness checks.

Point MCP clients at it with an HTTP transport config:

{ "mcpServers": { "roam-research-mcp": { "type": "http", "url": "http://127.0.0.1:8088/mcp" } } }

Env vars (tokens, graphs) live with theserverprocess, not the client config.

Securing an exposed server (two layers):If you bind beyond loopback (-H 0.0.0.0), add the perimeter lock:

HTTP_AUTH_TOKEN=$(openssl rand -hex 32) roam server start -H 0.0.0.0

Clients then send the token as a header:

{ "mcpServers": { "roam-research-mcp": { "type": "http", "url": "http://<host>:8088/mcp", "headers": { "Authorization": "Bearer <token>" } } } }

⚠️ The write key isnota substitute for the bearer token. On an exposed server withoutHTTP_AUTH_TOKEN, anyone on the network can stillread every graph(and write non-protected ones). For anything beyond loopback, setHTTP_AUTH_TOKEN.

Keeping it running (macOS LaunchAgent):Create~/Library/LaunchAgents/com.example.roam-mcp.plistwithRunAtLoad+KeepAlive, your env vars underEnvironmentVariables, and--serveras the lastProgramArgumentsentry. KeepStandardOutPath/StandardErrorPathon alocalpath (e.g.~/Library/Logs/), then:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.roam-mcp.plist curl -s http://127.0.0.1:8088/health # verify

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

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

Pinning the version.npx -y roam-research-mcpfetches thelatestrelease every time your client starts the server, so a new major version arrives without warning. Pin the major to decide for yourself when to move:

Pinning the major is the sensible default: you still get fixes and new tools, but a breaking change becomes something you opt into. The examples below stay unpinned to match what most people paste in first.