Roam Research MCP Server
A Model Context Protocol (MCP) server that provides tools to interact with Roam Research API, enabling Claude Desktop to read from and write to your Roam Research graph.
Features
- Get Page Content: Retrieve content from any page with nested child blocks in markdown format
- Get Page References: Find all references to a specific page with pagination support and time-based sorting
- Write to Page: Add new blocks to existing pages
- Write to Today: Add content to today's daily page (auto-creates if needed)
- Markdown Conversion: Automatically converts Roam-style
[[links]]to markdown format - Nested Block Support: Handles hierarchical block structures with proper indentation
Installation
Prerequisites
- Python 3.11+
- uv package manager
- Roam Research API token and graph access
Setup
- Clone the repository:
git clone <repository-url>
cd roam-research-mcp
- Install dependencies:
uv sync
- Set up environment variables:
export ROAM_TOKEN="your_roam_research_api_token"
export ROAM_GRAPH_NAME="your_graph_name"
Claude Desktop Integration
Add this configuration to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"roam-research": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/roam-research-mcp",
"run",
"python",
"main.py"
],
"env": {
"ROAM_TOKEN": "your_actual_roam_token",
"ROAM_GRAPH_NAME": "your_graph_name"
}
}
}
}
Usage
Once configured with Claude Desktop, you can:
- Ask Claude to read content from your Roam pages
- Have Claude write notes and thoughts to your daily pages
- Query page references and connections
- Add structured content to specific pages
Development
See CLAUDE.md for development guidelines and git commit conventions.
API Requirements
- Valid Roam Research API token
- Graph name with API access enabled
- Network access to
api.roamresearch.com
License
MIT License