README.md•2.25 kB
# 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](https://docs.astral.sh/uv/) package manager
- Roam Research API token and graph access
### Setup
1. Clone the repository:
```bash
git clone <repository-url>
cd roam-research-mcp
```
2. Install dependencies:
```bash
uv sync
```
3. Set up environment variables:
```bash
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`
```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](./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