PhiloSolares roam mcp

PhiloSolares roam mcp avatar

by PhiloSolares

A Model Context Protocol (MCP) server that connects Claude and other AI assistants to your Roam Research graph.

What is PhiloSolares roam mcp

Roam Research MCP Server

A Model Context Protocol (MCP) server that connects Claude and other AI assistants to your Roam Research graph.

What This Does

This server acts as a bridge between AI assistants and your Roam Research database. After setup, you can simply ask Claude to work with your Roam data - no coding required.

For example, you can say:

  • "Add these meeting notes to today's daily note in Roam"
  • "Search my Roam graph for blocks tagged with #ProjectIdeas"
  • "Create a new page in Roam called 'Project Planning'"
  • "Find all TODO items I created this month"

Features

Content Creation

  • Create new pages with nested content and headings
  • Add blocks to any page with proper hierarchy
  • Create structured outlines with customizable nesting
  • Import markdown with proper nesting
  • Add todo items with automatic TODO status
  • Update existing content individually or in batches
  • Modify block content with pattern transformations

Search and Retrieval

  • Find pages and blocks by title, text, or tags
  • Search for TODO/DONE items with filtering options
  • Find recently modified content
  • Search block references and explore block hierarchies
  • Search by creation or modification dates
  • Navigate parent-child relationships in blocks
  • Execute custom Datalog queries for advanced needs

Memory System

  • Store information for Claude to remember across conversations
  • Recall stored memories with filtering and sorting options
  • Tag memories with custom categories
  • Access both recent and older memories with flexible retrieval

URL Content Processing

  • Extract and import content from webpages
  • Parse and extract text from PDF documents
  • Retrieve YouTube video transcripts
  • Intelligently detect content type and process accordingly

Setup Instructions

  1. Install Claude Desktop from https://claude.ai/download

  2. Edit your Claude Desktop configuration file:

    • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  3. Add this configuration:

{
  "mcpServers": {
    "roam-helper": {
      "command": "uvx",
      "args": ["git+https://github.com/PhiloSolares/roam-mcp.git"],
      "env": {
        "ROAM_API_TOKEN": "<your_roam_api_token>",
        "ROAM_GRAPH_NAME": "<your_roam_graph_name>"
      }
    }
  }
}
  1. Get your Roam API token:
    • Go to your Roam Research graph settings
    • Navigate to "API tokens"
    • Click "+ New API Token"
    • Copy the token to your configuration

How to Use

Once set up, simply chat with Claude and ask it to work with your Roam graph. Claude will use the appropriate MCP commands behind the scenes.

Example conversations:

Creating Content:

You: "Claude, please create a new page in my Roam graph called 'Project Ideas' with a section for mobile app ideas."

Searching Content:

You: "Find all blocks in my Roam graph tagged with #ProjectIdeas that also mention mobile apps."

You: "Show me all the TODO items I created this week."

Using the Memory System:

You: "Remember that I want to use spaced repetition for learning JavaScript."

Later: You: "What learning techniques have we discussed for programming?"

Working with External Content:

You: "Extract the main points from this PDF and add them to my Roam graph."

You: "Get the transcript from this YouTube video about productivity."

Advanced Configuration

By default, memories are stored with the tag #[[Memories]]. To use a different tag:

"env": {
  "ROAM_API_TOKEN": "your-token",
  "ROAM_GRAPH_NAME": "your-graph",
  "MEMORIES_TAG": "#[[Claude/Memories]]"
}

Docker Support

You can run the Roam MCP server in a Docker container:

Building the Image

docker build -t roam-mcp .

Running the Container

Run with environment variables:

docker run -p 3000:3000 \
  -e ROAM_API_TOKEN="your_api_token" \
  -e ROAM_GRAPH_NAME="your_graph_name" \
  roam-mcp

Using with Claude Desktop

Configure Claude Desktop to use the containerized server:

{
  "mcpServers": {
    "roam-helper": {
      "command": "docker",
      "args": ["run", "--rm", "-p", "3000:3000",
               "-e", "ROAM_API_TOKEN=your_token",
               "-e", "ROAM_GRAPH_NAME=your_graph",
               "roam-mcp"],
      "env": {}
    }
  }
}

License

MIT License

Leave a Comment

Frequently Asked Questions

What is MCP?

MCP (Model Context Protocol) is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications, providing a standardized way to connect AI models to different data sources and tools.

What are MCP Servers?

MCP Servers are lightweight programs that expose specific capabilities through the standardized Model Context Protocol. They act as bridges between LLMs like Claude and various data sources or services, allowing secure access to files, databases, APIs, and other resources.

How do MCP Servers work?

MCP Servers follow a client-server architecture where a host application (like Claude Desktop) connects to multiple servers. Each server provides specific functionality through standardized endpoints and protocols, enabling Claude to access data and perform actions through the standardized protocol.

Are MCP Servers secure?

Yes, MCP Servers are designed with security in mind. They run locally with explicit configuration and permissions, require user approval for actions, and include built-in security features to prevent unauthorized access and ensure data privacy.

Submit Your MCP Server

Share your MCP server with the community

Submit Now