Roam Tools MCP Server
Read, write, search, and query your Roam Research graph directly from AI agents.
Data last scanned today · Reviewed today
Overview
Roam Tools MCP Server bridges the gap between AI assistants and your local Roam Research desktop application. By connecting to the Roam local HTTP API, it enables models like Claude to traverse your graph, retrieve information, and perform operations on pages and blocks. This utility provides both an interactive CLI for initial setup and non-interactive modes for automated agent workflows. It supports granular access levels, allowing users to choose between full write capabilities or more restricted read-only permissions depending on their requirements.
Our verdict
With a security score of 30/100, this server is considered high-risk. It grants AI models full write access to your Roam graph, and because Roam lacks a traditional undo history, deletions or bulk modifications made by an agent may be irreversible. Given the lack of a detected license and the fact that authentication and read-only mode safety have not been editorially reviewed, this tool should be used with extreme caution. It is intended for users who are comfortable managing raw graph data, performing manual backups, and verifying every action before execution in a test environment.
- Supports non-interactive CLI modes for automated agent integration
- Zero direct dependencies minimize the software supply-chain surface
- Active development with commits as recent as six days ago
- Full write access poses high risk of irreversible data loss
- No license detected, creating legal ambiguity regarding use
- Requires Roam Research desktop app specifically
Setup
{
"mcpServers": {
"roam-tools": {
"args": [
"-y",
"roam-tools"
],
"command": "npx"
}
}
}Paste into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart Claude Desktop. Some servers require API keys or tokens as environment variables — check the project's README and add an "env" object if needed.
- No read-only mode — running this grants full read/write access.
- No built-in authentication — anyone with access to this config can invoke every tool it exposes.
Tools
| Tool | Description | Risk |
|---|---|---|
| list_graphs | List all configured graphs with their nicknames | low |
| setup_new_graph | Set up a new graph connection, or list available graphs | medium |
| get_graph_guidelines | Returns user-defined instructions and preferences for AI agents | low |
| create_page | Create page with markdown content | medium |
| update_page | Update page title or children view type | medium |
| delete_page | Delete a page | high |
| create_block | Create blocks | medium |
| append_to_daily_note | Append/capture markdown to a daily note | medium |
| update_block | Update block content/properties | medium |
| move_block | Move a block to a new location | medium |
Compatibility
| Client | Local | Docker | Remote | Read-only |
|---|---|---|---|---|
| Claude Desktop | ||||
| Cursor | ||||
| VS Code | ||||
| Windsurf | ||||
| ChatGPT |
Frequently asked questions
›Does this server work with the Roam Research web app?
No, this MCP server requires the Roam Research desktop application because it interacts with the local HTTP API, which is not available in the web version.
›Can I undo changes made by an AI assistant using this server?
Roam does not have a traditional undo history that can reverse bulk operations or deletions performed through the API. It is highly recommended to back up your graph before use and test on a separate graph first.
›What should I do if I have multiple Roam graphs configured?
If you have multiple graphs configured, you must specify the nickname assigned to the graph in each tool call to ensure the correct graph is accessed.
›Do I need to approve token access manually?
Yes, both interactive and non-interactive setup modes require a human to manually approve the token dialog within the Roam desktop application.
›Can I manually configure the server without using the CLI?
Yes, you can manually create a ~/.roam-tools.json file containing your graph name, nickname, and the local API token generated within Roam Desktop settings.
›How do I ensure the server stays connected?
The server automatically attempts to launch the Roam desktop app via deep link if it is not running when a tool is called.
Badge
Maintain this server? Add the live badge to your README.