Name: Roam Research
Author: PhiloSolares

LABSCO SUMMARY

Searches the graph as a graph, and brings outside content into it.

Block references, parent-child navigation and raw Datalog mean questions like "what links here" work properly, which flat text search cannot answer. The URL handling is the other half: a PDF or a video becomes notes inside Roam rather than a link you meant to read. Everything runs against a live graph with a write-capable token, so it creates and edits real pages.

What it is

A Python bridge between an assistant and a Roam Research graph. It covers writing structured content, searching the graph the way Roam itself thinks about it — blocks, references, hierarchy — and a memory layer that persists what you tell it to remember across conversations.

What you get

Content creation: new pages with nested content and headings, blocks placed in the right hierarchy, structured outlines, Markdown import that keeps its nesting, and todo items with TODO status
Updates individually or in batches, including pattern transformations on block content
Search by title, text or tag; TODO and DONE items with filters; recently modified content; block references and hierarchy; creation and modification dates
Custom Datalog queries when the built-in searches are not specific enough
A memory system that stores and recalls facts across conversations, tagged for filtering
URL handling that detects content type: web page extraction, PDF text extraction and YouTube transcripts

Requirements

A Roam API token created under your graph's settings, plus the graph name — ROAM_API_TOKEN and ROAM_GRAPH_NAME. Launch with uvx git+https://github.com/PhiloSolares/roam-mcp.git, or build the Docker image and run it on port 3000. MEMORIES_TAG changes the default #[[Memories]] tag. The Python package is roam-mcp, version 0.2.0, with the entry point roam-mcp.

Setup effort

One command plus a key — uvx git+https://github.com/PhiloSolares/roam-mcp.git, then supply credentials

See installation options

USE CASES

01

Getting meeting notes into the daily note

Dictate the notes and have them filed with the right nesting instead of pasting a flat block.

02

Finding everything under a tag

Search for blocks tagged with a project and narrow by what they mention.

03

Reviewing what you committed to

Pull TODO items created in a given period rather than scrolling daily notes.

04

Turning a source into notes

Extract a PDF's text or a video's transcript and write the key points into the graph.

05

Making the assistant remember a preference

Store it under the memories tag so a later conversation can recall it.

BEFORE YOU INSTALL

What to know first

Requires

uvx on PATH
ROAM_API_TOKEN in your environment

Where it runs

Both documented setups run the server on your machine.

INSTALLATION

Connect your client

Server setup

TERMINAL

uvx git+https://github.com/PhiloSolares/roam-mcp.git

MCP Clients

Claude Desktop — uvx

CLAUDE DESKTOP — UVX · JSON

{
  "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>"
      }
    }
  }
}

Claude Desktop — Docker

CLAUDE DESKTOP — DOCKER · JSON

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

Roam Research