Roam Research MCP and CLI
An agent searches, reads and writes a Roam Research graph through the desktop app's local API, with a CLI and a syntax skill
- 62 ★ on the repository
- Last commit
Broad access
Why this level
- At the `full` level the agent creates, edits and deletes pages and blocks, and bulk changes in Roam cannot be undone
- Blocks hidden with `#.rm-hide` and `#.rm-private` remain reachable through `datalog_query`
- The token acts on a whole graph, and the server does not check the access level; Roam itself does
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/roam-research-mcp-and-cliDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- At the `full` level the agent creates, edits and deletes pages and blocks, and bulk changes in Roam cannot be undone
- Blocks hidden with `#.rm-hide` and `#.rm-private` remain reachable through `datalog_query`
- The token acts on a whole graph, and the server does not check the access level; Roam itself does
This is third-party code. Review the repository files before installing.
What it does
The official Roam Research MCP server and command-line client connect an agent to a knowledge graph. The agent searches pages and blocks, reads pages as Markdown, looks at backlinks, creates and edits blocks, appends notes to the daily page and writes Datalog queries. The server calls the local HTTP API of the Roam desktop app and launches the app itself through a deep link when needed. The web version does not work. Access is set by a token: `npx @roam-research/roam-mcp connect` walks through choosing a graph and a permission level (`full`, `read-append` or `read-only`), and the person approves the token in the Roam window. The repository holds a `roam-syntax` skill. It teaches the agent Roam's markup (italics are written `__text__`) and the shape of the read tools' output so that writing does not break block references. Blocks tagged `#.rm-hide` and `#.rm-private` are skipped by the read tools.
Who it is for. Roam Research users with the desktop app who keep notes in a graph and want to hand an agent searching, sorting and adding to it.
Good fit when
- The result of a work session is added to the daily page with one request to the agent
- A topic digest is assembled: the agent searches pages, reads backlinks and suggests links to existing pages
- A complex selection over the graph is solved with a Datalog query that the agent writes itself
- A working graph is connected read-only, and the public `help` graph is read like a reference
Not a fit when
- You use the web version of Roam: the local API exists only in the desktop app
- The graph has no backup: pages and blocks deleted by the agent may be impossible to restore
- Permissions must be limited on the server side: the `accessLevel` field in the configuration file only records the granted level, and the Roam token defines the rights
Example request
Add the results of the work session to today's daily note and find Roam pages worth linking to from the text.MCP
- Transport
- stdio
- Authentication
- API key
Limitations
The project is at the alpha stage and breaking changes are possible. It needs Node.js 18 or newer and the Roam desktop app.
At the `full` level the agent can create, edit and delete pages and blocks, and Roam has no undo history for bulk operations. The `#.rm-hide` and `#.rm-private` filter does not apply everywhere: `datalog_query` reads the database directly and shows hidden blocks, and the template preview in `search_templates` does not hide them.
How to disable. Remove the server from Claude Code with `claude mcp remove roam-mcp`. `npx @roam-research/roam-mcp connect --remove --graph <name>` drops the connection to a graph, and the tokens live in the Roam graph settings under Local API Tokens.
FAQ
How do I connect Roam to Claude Code?
First run `npx @roam-research/roam-mcp connect`: it walks through choosing a graph and permissions, and you approve the token in the Roam app. Then run `claude mcp add -s user roam-mcp -- npx -y @roam-research/roam-mcp`. For a single project use `-s local` instead of `-s user`.
Does the server work with the web version of Roam?
No. The local API exists only in the desktop app, which must be installed. If Roam is closed, the server opens it through a deep link and retries the connection.
Can the agent get read-only access?
Yes. Choose the `read-only` level during `connect`; `read-append` and `full` also exist. A public graph is connected with the `--public` flag and is read-only.
How do I work with several graphs?
Run `connect` for each graph and give each a short name. A single graph is selected automatically; with several, the agent passes the name in the `graph` parameter.
How do I give the agent rules for working with the graph?
Create a page `[[roam/agent guidelines]]` with instructions: the `get_graph_guidelines` tool returns them to the agent. You can record naming conventions, page structure and topics there.
Discussion
No questions or reviews yet.
Related
MCP serversA local Markdown note base with an MCP server and skills: Claude Code, Cursor, Codex and Gemini CLI all read the same context
mcp-logseq: MCP server for Logseq
MCP server for LogSeq
MCP server for Logseq: the agent reads, searches and edits pages and blocks of your graph over the local HTTP API
DoodleNote MCP: meeting notes for agents
DoodleNote MCP
A read-only MCP server: Claude Code, Claude Desktop and Codex search local DoodleNote meetings, notes and transcripts
A Rust MCP server for a folder of Markdown notes: an agent searches and reads notes and sees backlinks, tags, tasks and version history
Serverless notes on Cloudflare Workers with an MCP endpoint and a skill so agents can search and write your notes
An MCP server and CLI that find in Claude Code and Codex sessions why a file became what it is: who asked the agent what, when and what changed
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Roam Research MCP and CLI (this card) | yes | API key | 62 | |
| mcp-obsidian | no | API key | 4,520 | notes in Obsidian, does not read a Roam graph |
| mcp-logseq: MCP server for Logseq | no | API key | 350 | a graph in Logseq, not in Roam |
| Notion MCP Server | yes | API key | 4,698 | a Notion workspace, a different data model |
README in short
The documentation covers connecting a graph in interactive and non-interactive modes, manual setup of `~/.roam-tools.json`, the tools grouped by purpose and working with several graphs. The repository is a monorepo of four packages: the core, a local transport, the MCP server and the CLI.