SkillFoxx

Roam Research MCP

An MCP server and CLI that read and write a Roam Research graph through the backend API, without the app running.

  • 100 ★ on the repository
  • Last commit
  • MIT
MCP server

Extended access

Why this level

  • The graph token gives read and write access to the whole graph and batch actions can delete blocks.
  • An HTTP daemon without an access token exposes the graph to the whole network.
All reasons and checks

2b3pro/roam-research-mcpAuthor:2b3pro

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add mcp/roam-research-mcp

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

  • The graph token gives read and write access to the whole graph and batch actions can delete blocks.
  • An HTTP daemon without an access token exposes the graph to the whole network.

This is third-party code. Review the repository files before installing.

What it does

Roam Research MCP, an MCP server and `roam` command-line program, gives an agent access to a Roam Research notes graph. Tools search pages and blocks, read pages with backlinks, create pages, tables and outlines, move blocks, track tasks and run Datalog queries. A page updates through smart diffing and keeps block identifiers, so references to them do not break. The server calls the Roam backend API with a graph token and does not need the desktop app. It runs over stdio or as a shared `roam server` HTTP daemon. Several graphs connect to one server and writes to chosen ones are locked with a `write_key`. There is deliberately no page-deletion tool.

Who it is for. Roam Research users who keep notes in a graph and want Claude Code or another MCP client to search, extend and tidy them.

Good fit when

  • An agent finds all blocks with a tag or TODO in the graph and builds a summary.
  • Thoughts and tasks go to the daily page with `roam save`, including from a pipeline.
  • The graph is needed on a server, container or CI where desktop Roam is not running.
  • Several graphs connect to one server and writes to the work graph are locked with a key.

Not a fit when

  • The Roam Desktop interface and embedding search are better handled by the official Roam server, which offers them.
  • The graph token cannot go to a third-party package: it sits in the server's environment variables.
  • Pages are meant to be deleted through the server: this package has no such tool.

Example request

Find all blocks with a project tag in the graph, show them by page and add a TODO to today's page.

MCP

Transport
stdio, http
Authentication
API key

Environment variables

ROAM_API_TOKEN required, secret
Roam graph API token
ROAM_GRAPH_NAME required
Roam graph name
HTTP_AUTH_TOKEN secret
Access token for the shared HTTP daemon beyond loopback
HTTP_STREAM_PORT
Port of the shared HTTP daemon

Limitations

A Roam API token and the graph name are required and live in the server's environment variables. A shared HTTP daemon on `0.0.0.0` without `HTTP_AUTH_TOKEN` opens reading of all graphs to anyone on the network. The `write_key` protects only writes to protected graphs. `npx -y roam-research-mcp` pulls the latest version on every start, so pin the major version. Blocks tagged `#.rm-hide` and `#.rm-private` are withheld from the agent.

How to disable. Remove the `roam-research` entry from the MCP client settings and stop the daemon with `roam server stop` if you ran it. Delete the graph token in the environment and files in `~/.roam/` separately.

FAQ

How does it differ from the official Roam server?

The official one uses the Roam Desktop local API and needs the app running. This one uses the backend API, runs headless and adds a CLI, a shared HTTP daemon, batch operations and agent memory.

How do I connect several graphs?

With the `ROAM_GRAPHS` variable holding tokens and graph names. Writing to a protected graph needs a `write_key`.

How do I hide blocks from the AI?

With `#.rm-hide` and `#.rm-private` tags: the server withholds such blocks. The tags are shared with the official server.

How do I run the shared daemon?

With `roam server start`, the port is set by `HTTP_STREAM_PORT`. Beyond loopback always set `HTTP_AUTH_TOKEN`.

How do I save a thought from the terminal?

With `roam save "idea"` or a pipe: `echo "Buy milk" | roam save --todo`.

Discussion

No questions or reviews yet.

MCP servers
Official

An agent searches, reads and writes a Roam Research graph through the desktop app's local API, with a CLI and a syntax skill

MCP serverBroad access62
Official

Atlassian's official cloud MCP server for Jira, Confluence, Jira Service Management, Bitbucket, Compass and Loom, with skills

MCP serverBroad access1.2K

The MCP endpoint of a Salt workspace on your server: an agent creates pages, databases and comments with a person rights.

MCP serverBroad access178

MCP server for Logseq: the agent reads, searches and edits pages and blocks of your graph over the local HTTP API

MCP serverBroad access351
Official

A read-only MCP server: Claude Code, Claude Desktop and Codex search local DoodleNote meetings, notes and transcripts

MCP serverExtended access186
Official

The official Kibela MCP server searches, reads and edits notes, folders and comments of your wiki straight from an assistant chat

MCP serverExtended access16

README in short

The README starts with a story: the author wanted to manage a graph from Claude Code and the tools grew into a standalone CLI. Versions 6.0 and 6.1 are covered separately: consistent search pagination and a `BLOCK_NOT_FOUND` reply instead of false success on delete.

README badge

Report a problem