The guidelines page is the distinctive move: your tagging and namespacing conventions live in the graph as [[roam/agent guidelines]], and the tools nudge the agent to load them once per session so a write lands in your system rather than a generic one. For heavy edits, roam_process_batch_actions is the tool that keeps you inside Roam's rate limits — batching operations rather than firing them one at a time.
A server and standalone CLI for a Roam Research graph: 25 tools covering page and block reads, structured writes, search across the block hierarchy, a memory store, and raw Datomic queries. It reads its own operating rules from a page inside your graph.
- roam_get_guidelines reads a [[roam/agent guidelines]] page in your graph — how you tag, how you name and namespace pages, what never to do — and the other tools tell the agent to call it once per session first, because conventions change how results are read as well as written
- Pages created and edited whole: roam_create_page with an outline in one step, roam_create_outline to add structure to an existing page, roam_update_page_markdown with a smart diff that preserves block UIDs, and roam_rename_page
- roam_create_table abstracts Roam's error-prone nested table structure, and roam_import_markdown drops nested markdown under a specific block, creating the parent if it is missing
- Reads that mirror the Roam UI: roam_fetch_page_by_title, roam_fetch_block with children and ancestors, and roam_fetch_page_full_view which returns a page plus its backlinks grouped by source with breadcrumb context
- Search across the graph — roam_search_by_text (including namespace-prefix page search), roam_search_for_tag, roam_search_by_status for TODO/DONE, roam_search_block_refs, roam_search_hierarchy up or down the block tree, roam_search_by_date and roam_find_pages_modified_today — all paginated
- roam_datomic_query runs a custom Datomic query straight against Roam's engine for filtering the search tools cannot express, including regex
- roam_process_batch_actions combines many create/update/delete block operations into one call — the rate-limit-efficient path for intensive edits — with roam_move_block as a single-move wrapper over it
- roam_add_todo drops todos onto today's daily page, and roam_remember / roam_recall keep a tagged memory store on the graph
- roam_get_subpages returns a page's namespace children, and roam_markdown_cheatsheet hands the agent the full Roam-flavored syntax reference
A Roam Research API token and your graph name, set as ROAM_API_TOKEN and ROAM_GRAPH_NAME in the environment or a .env file that lives with the server process. Node, launched as npx roam-research-mcp over stdio, or with --server for HTTP streaming (HTTP_STREAM_PORT, default 8088). ROAM_GRAPHS configures several graphs at once with per-graph write_key protection, and ROAM_MEMORIES_TAG sets the default tag roam_remember and roam_recall use.
One command plus a key — npx roam-research-mcp, then supply credentials