Skip to main content
Glama

Servidor MCP de Roam Research

versión npm Estado del proyecto: WIP – El desarrollo inicial está en progreso, pero aún no hay una versión estable y utilizable adecuada para el público. Licencia: MIT GitHub

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona acceso completo a la funcionalidad de la API de Roam Research. Este servidor permite que asistentes de IA como Claude interactúen con su gráfico de Roam Research a través de una interfaz estandarizada. (Un proyecto personal en desarrollo, no avalado oficialmente por Roam Research).

Instalación

Puede instalar el paquete globalmente:

npm install -g roam-research-mcp

O clonar el repositorio y compilar desde la fuente:

git clone https://github.com/2b3pro/roam-research-mcp.git
cd roam-research-mcp
npm install
npm run build

Related MCP server: Roam Research MCP Server

Para probar

Ejecutar MCP Inspector después de la compilación…

npx @modelcontextprotocol/inspector node build/index.js

Características

El servidor proporciona herramientas potentes para interactuar con Roam Research:

  • Manejo de variables de entorno con soporte .env

  • Validación de entrada integral

  • Coincidencia de títulos de páginas sin distinción entre mayúsculas y minúsculas

  • Resolución de referencia de bloque recursiva

  • Análisis y conversión de Markdown

  • Integración de páginas diarias

  • Registro de depuración detallado

  • Operaciones por lotes eficientes

  • Creación de esquemas jerárquicos

  1. roam_fetch_page_by_title : recupera y lee el contenido de una página por título, resolviendo recursivamente referencias de bloque hasta 4 niveles de profundidad

  2. roam_create_page : Crea nuevas páginas con contenido opcional

  3. roam_create_block : Crea nuevos bloques en una página (por defecto, la página diaria de hoy)

  4. roam_import_markdown : Importa contenido de Markdown anidado bajo bloques específicos

  5. roam_add_todo : agrega múltiples elementos de tareas pendientes a la página diaria de hoy con sintaxis de casilla de verificación

  6. roam_create_outline : Crea esquemas jerárquicos con anidamiento y estructura adecuados

  7. roam_search_block_refs : busca referencias de bloques dentro de las páginas o en el gráfico

  8. roam_search_hierarchy : Navegar y buscar a través de las relaciones padre-hijo del bloque

  9. roam_find_pages_modified_today : Encuentra todas las páginas que han sido modificadas desde la medianoche de hoy

  10. roam_search_by_text : busca bloques que contengan texto específico en todas las páginas o dentro de una página específica

  11. roam_update_block : Actualiza el contenido del bloque con texto directo o transformaciones basadas en patrones

  12. roam_search_by_date : busca bloques y páginas según las fechas de creación o modificación

  13. roam_search_for_tag : busca bloques que contengan etiquetas específicas con filtrado opcional por etiquetas cercanas

  14. roam_remember : Almacena y categoriza recuerdos o información con etiquetado automático

  15. roam_recall : Recupera recuerdos de bloques marcados con la etiqueta MEMORIES_TAG (ver más abajo) o bloques en el título de la página del mismo nombre

  16. roam_datomic_query : Ejecuta consultas de registro de datos personalizadas en el gráfico de Roam para la recuperación y el análisis avanzados de datos

Configuración

  1. Crear un token de API de Roam Research :

    • Vaya a la configuración de sus gráficos

    • Vaya a la sección "Tokens de API" (Configuración > pestaña "Gráfico" > sección "Tokens de API" y haga clic en el botón "+ Nuevo token de API").

    • Crear un nuevo token

  2. Configurar las variables de entorno: Tiene dos opciones para configurar las variables de entorno requeridas:

    Opción 1: Usar un archivo .env (recomendado para desarrollo) Cree un archivo .env en el directorio roam-research:

    ROAM_API_TOKEN=your-api-token
    ROAM_GRAPH_NAME=your-graph-name
    MEMORIES_TAG='#[[LLM/Memories]]'

    Opción 2: Usar la configuración de MCP (método alternativo) Agregue la configuración a su archivo de configuración de MCP:

    • Para Cline ( ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ):

    • Para la aplicación de escritorio Claude ( ~/Library/Application Support/Claude/claude_desktop_config.json ):

    {
      "mcpServers": {
        "roam-research": {
          "command": "node",
          "args": ["/path/to/roam-research-mcp/build/index.js"],
          "env": {
            "ROAM_API_TOKEN": "your-api-token",
            "ROAM_GRAPH_NAME": "your-graph-name",
            "MEMORIES_TAG": "#[[LLM/Memories]]"
          }
        }
      }
    }

    Nota: El servidor primero intentará cargar desde el archivo .env y luego recurrirá a las variables de entorno de la configuración de MCP.

  3. Construya el servidor (asegúrese de estar en el directorio raíz del MCP):

    cd roam-research-mcp
    npm install
    npm run build

Uso

Obtener página por título

Obtener y leer el contenido de una página con referencias de bloque resueltas:

use_mcp_tool roam-research roam_fetch_page_by_title {
  "title": "Example Page"
}

Devuelve el contenido de la página como markdown con:

  • Estructura jerárquica completa

  • Referencias de bloque resueltas recursivamente (hasta 4 niveles de profundidad)

  • Sangría adecuada para niveles de anidamiento

  • Formato de rebajas completo

Crear página

Crear una nueva página con contenido opcional:

use_mcp_tool roam-research roam_create_page {
  "title": "New Page",
  "content": "Initial content for the page"
}

Devuelve el UID de la página creada en caso de éxito.

Crear bloque

Agregar un nuevo bloque a una página (el valor predeterminado es la página diaria de hoy si no se proporciona ni page_uid ni title):

use_mcp_tool roam-research roam_create_block {
  "content": "Block content",
  "page_uid": "optional-target-page-uid",
  "title": "optional-target-page-title"
}

Puede especificar:

  • page_uid : Referencia directa a la página de destino

  • title : Nombre de la página de destino (se creará si no existe)

  • Ninguno: Se agregará un bloque a la página diaria de hoy.

Devoluciones:

{
  "success": true,
  "block_uid": "created-block-uid",
  "parent_uid": "parent-page-uid"
}

Crear esquema

Crear un esquema jerárquico con anidación y estructura adecuadas:

use_mcp_tool roam-research roam_create_outline {
  "outline": [
    {
      "text": "I. Top Level",
      "level": 1
    },
    {
      "text": "A. Second Level",
      "level": 2
    },
    {
      "text": "1. Third Level",
      "level": 3
    }
  ],
  "page_title_uid": "optional-target-page",
  "block_text_uid": "optional-header-text"
}

Características:

  • Cree contornos complejos con hasta 10 niveles de anidamiento

  • Validar la estructura y el contenido del esquema

  • Mantener relaciones adecuadas entre padres e hijos

  • Bloque de encabezado opcional para el esquema

  • El valor predeterminado es la página diaria de hoy si no se especifica ninguna página

  • Operaciones por lotes eficientes para crear bloques

Parámetros:

  • outline : Matriz de elementos de esquema, cada uno con:

    • text : Contenido del elemento del esquema (obligatorio)

    • level : Nivel de anidamiento (1-10, obligatorio)

  • page_title_uid : Título de la página de destino o UID (opcional, el valor predeterminado es la página de hoy)

  • block_text_uid : Texto de encabezado para el esquema (opcional)

Devoluciones:

{
  "success": true,
  "page_uid": "target-page-uid",
  "parent_uid": "header-block-uid",
  "created_uids": ["uid1", "uid2", ...]
}

Agregar elementos de tareas pendientes

Agregue uno o más elementos de tareas pendientes a la página diaria de hoy:

use_mcp_tool roam-research roam_add_todo {
  "todos": [
    "First todo item",
    "Second todo item",
    "Third todo item"
  ]
}

Características:

  • Agrega todos con sintaxis de casilla de verificación Roam ( {{TODO}} todo text )

  • Admite agregar varias tareas pendientes en una sola operación

  • Utiliza acciones por lotes para lograr eficiencia al agregar más de 10 tareas pendientes

  • Crea automáticamente la página de hoy si no existe

  • Agrega tareas pendientes como bloques de nivel superior en orden secuencial

Importar Markdown anidado

Importar contenido de Markdown anidado bajo un bloque específico:

use_mcp_tool roam-research roam_import_markdown {
  "content": "- Item 1\n  - Subitem A\n  - Subitem B\n- Item 2",
  "page_uid": "optional-page-uid",
  "page_title": "optional-page-title",
  "parent_uid": "optional-parent-block-uid",
  "parent_string": "optional-exact-block-content",
  "order": "first"
}

Características:

  • Importar contenido bajo bloques específicos:

    • Buscar bloque padre por UID o coincidencia exacta de cadena

    • Localizar bloques dentro de páginas específicas por título o UID

    • Se establece como predeterminado la página de hoy si no se especifica ninguna página

  • Controlar la ubicación del contenido:

    • Agregar como primer o último hijo del bloque padre

    • Preservar la estructura jerárquica

    • Operaciones por lotes eficientes para contenido anidado

  • Valor de retorno integral:

    {
      "success": true,
      "page_uid": "target-page-uid",
      "parent_uid": "parent-block-uid",
      "created_uids": ["uid1", "uid2", ...]
    }

Parámetros:

  • content : Contenido de rebajas anidado para importar

  • page_uid : UID de la página que contiene el bloque padre

  • page_title : Título de la página que contiene el bloque padre (se ignora si se proporciona page_uid)

  • parent_uid : UID del bloque padre bajo el cual se agregará contenido

  • parent_string : contenido exacto de la cadena del bloque padre (debe proporcionar page_uid o page_title)

  • order : Dónde agregar el contenido ("primero" o "último", predeterminado "primero")

Referencias del bloque de búsqueda

Busque referencias de bloques dentro de las páginas o en todo el gráfico:

use_mcp_tool roam-research roam_search_block_refs {
  "block_uid": "optional-block-uid",
  "page_title_uid": "optional-page-title-or-uid"
}

Características:

  • Encuentra todas las referencias a un bloque específico

  • Busque cualquier referencia de bloque dentro de una página

  • Buscar en todo el gráfico

  • Admite referencias tanto directas como indirectas

  • Incluye contenido de bloque y contexto de ubicación.

Parámetros:

  • block_uid : UID del bloque al que se buscarán referencias (opcional)

  • page_title_uid : Título o UID de la página donde buscar (opcional)

Devoluciones:

{
  "success": true,
  "matches": [
    {
      "block_uid": "referenced-block-uid",
      "content": "Block content with ((reference))",
      "page_title": "Page containing reference"
    }
  ],
  "message": "Found N block(s) referencing..."
}

Buscar por texto

Busque bloques que contengan texto específico en todas las páginas o dentro de una página específica:

use_mcp_tool roam-research roam_search_by_text {
  "text": "search text",
  "page_title_uid": "optional-page-title-or-uid",
  "case_sensitive": true
}

Características:

  • Busque cualquier texto en todos los bloques del gráfico

  • Búsqueda opcional en el ámbito de la página

  • Búsqueda con o sin distinción entre mayúsculas y minúsculas

  • Devuelve el contenido del bloque con el contexto de la página.

  • Coincidencia de texto eficiente mediante consultas de registro de datos

Parámetros:

  • text : El texto a buscar (obligatorio)

  • page_title_uid : Título o UID de la página donde buscar (opcional)

  • case_sensitive : si se debe realizar una búsqueda que distinga entre mayúsculas y minúsculas (opcional, valor predeterminado: verdadero para que coincida con el comportamiento nativo de Roam)

Devoluciones:

{
  "success": true,
  "matches": [
    {
      "block_uid": "matching-block-uid",
      "content": "Block content containing search text",
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) containing \"search text\""
}

Actualizar el contenido del bloque

Actualice el contenido de un bloque utilizando reemplazo de texto directo o transformaciones basadas en patrones:

use_mcp_tool roam-research roam_update_block {
  "block_uid": "target-block-uid",
  "content": "New block content"
}

O utilice la transformación basada en patrones:

use_mcp_tool roam-research roam_update_block {
  "block_uid": "target-block-uid",
  "transform_pattern": {
    "find": "\\bPython\\b",
    "replace": "[[Python]]",
    "global": true
  }
}

Características:

  • Dos modos de actualización:

    • Reemplazo directo de contenido

    • Transformación basada en patrones usando expresiones regulares

  • Verificar la existencia del bloque antes de actualizar

  • Devolver contenido actualizado en respuesta

  • Soporte para reemplazos globales o de un solo partido

  • Preservar las relaciones de bloques y los metadatos

Parámetros:

  • block_uid : UID del bloque a actualizar (obligatorio)

  • content : Nuevo contenido para el bloque (si se usa reemplazo directo)

  • transform_pattern : Patrón para transformar contenido existente:

    • find : Texto o patrón de expresión regular para buscar

    • replace : Texto con el que reemplazar

    • global : si se deben reemplazar todas las ocurrencias (valor predeterminado: verdadero)

Devoluciones:

{
  "success": true,
  "content": "Updated block content"
}

Buscar etiquetas

Busque bloques que contengan etiquetas específicas con filtrado opcional por etiquetas cercanas:

use_mcp_tool roam-research roam_search_for_tag {
  "primary_tag": "Project/Tasks",
  "page_title_uid": "optional-page-title-or-uid",
  "near_tag": "optional-secondary-tag",
  "case_sensitive": true
}

Características:

  • Buscar bloques que contengan etiquetas específicas

  • Filtrado opcional por presencia de otra etiqueta

  • Búsqueda en el ámbito de la página o en todo el gráfico

  • Búsqueda con o sin distinción entre mayúsculas y minúsculas

  • Devuelve el contenido del bloque con el contexto de la página.

  • Coincidencia eficiente de etiquetas mediante consultas de registro de datos

Parámetros:

  • primary_tag : La etiqueta principal a buscar (obligatorio)

  • page_title_uid : Título o UID de la página donde buscar (opcional)

  • near_tag : Otra etiqueta para filtrar los resultados (opcional)

  • case_sensitive : si se debe realizar una búsqueda que distinga entre mayúsculas y minúsculas (opcional, valor predeterminado: verdadero para que coincida con el comportamiento nativo de Roam)

Devoluciones:

{
  "success": true,
  "matches": [
    {
      "block_uid": "matching-block-uid",
      "content": "Block content containing #[[primary_tag]]",
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) referencing \"primary_tag\""
}

Recordar información

Almacene recuerdos o información importante con etiquetado y categorización automáticos:

use_mcp_tool roam-research roam_remember {
  "memory": "Important information to remember",
  "categories": ["Work", "Project/Alpha"]
}

Características:

  • Almacenar información con la etiqueta #[[LLM/Memories]]

  • Agregar etiquetas de categoría opcionales para la organización

  • Se agrega automáticamente a la página diaria de hoy.

  • Admite múltiples categorías por memoria

  • Recuperación fácil usando roam_search_for_tag

  • Mantiene el orden cronológico de los recuerdos.

Parámetros:

  • memory : La información a recordar (obligatoria)

  • categories : Matriz opcional de categorías para etiquetar la memoria

Devoluciones:

{
  "success": true,
  "block_uid": "created-block-uid",
  "content": "Memory content with tags"
}

Buscar por fecha

Buscar bloques y páginas según fechas de creación o modificación:

use_mcp_tool roam-research roam_search_by_date {
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "type": "modified",
  "scope": "blocks",
  "include_content": true
}

Características:

  • Buscar por fecha de creación, fecha de modificación o ambas

  • Bloques de filtros, páginas o ambos

  • Rango de fechas opcional con fechas de inicio y finalización

  • Incluir o excluir contenido de bloque/página en los resultados

  • Ordenar resultados por marca de tiempo

  • Filtrado eficiente basado en fechas mediante consultas de registro de datos

Parámetros:

  • start_date : Fecha de inicio en formato ISO (AAAA-MM-DD) (obligatorio)

  • end_date : Fecha de finalización en formato ISO (AAAA-MM-DD) (opcional)

  • type : si desea buscar por 'creado', 'modificado' o 'ambos' (obligatorio)

  • scope : si se debe buscar 'bloques', 'páginas' o 'ambos' (obligatorio)

  • include_content : si se debe incluir el contenido de los bloques/páginas coincidentes (opcional, valor predeterminado: verdadero)

Devoluciones:

{
  "success": true,
  "matches": [
    {
      "uid": "block-or-page-uid",
      "type": "block",
      "time": 1704067200000,
      "content": "Block or page content",
      "page_title": "Page title (for blocks)"
    }
  ],
  "message": "Found N matches for the given date range and criteria"
}

Encuentra páginas modificadas hoy

Encuentra todas las páginas que han sido modificadas desde la medianoche de hoy:

use_mcp_tool roam-research roam_find_pages_modified_today {}

Características:

  • Realiza un seguimiento de todas las modificaciones realizadas en las páginas desde la medianoche.

  • Detecta cambios en cualquier nivel de la jerarquía de bloques.

  • Devuelve una lista única de títulos de páginas modificados

  • Incluye recuento de páginas modificadas

  • No se requieren parámetros

Devoluciones:

{
  "success": true,
  "pages": ["Page 1", "Page 2"],
  "message": "Found 2 page(s) modified today"
}

Ejecutar consultas Datomic

Ejecute consultas de registro de datos personalizadas en su gráfico Roam para recuperación y análisis de datos avanzados:

use_mcp_tool roam-research roam_datomic_query {
  "query": "[:find (count ?p)\n :where [?p :node/title]]",
  "inputs": []
}

Características:

  • Acceso directo al motor de consultas de Roam

  • Compatibilidad con todas las funciones de consulta de Datalog:

    • Coincidencia de patrones complejos

    • Funciones de agregación (contar, suma, máximo, mínimo, promedio, distinto)

    • Operaciones con cadenas (¿incluye?, ¿empieza con?, ¿termina con?)

    • Operaciones lógicas (<, >, <=, >=, =, not=)

    • Reglas para consultas recursivas

  • Capacidades de búsqueda que distinguen entre mayúsculas y minúsculas y que no lo distinguen entre mayúsculas y minúsculas

  • Consultas eficientes en todo el gráfico

Parámetros:

  • query : La consulta del registro de datos que se ejecutará (obligatorio)

  • inputs : Matriz opcional de parámetros de entrada para la consulta

Devoluciones:

{
  "success": true,
  "matches": [
    {
      "content": "[result data]",
      "block_uid": "",
      "page_title": ""
    }
  ],
  "message": "Query executed successfully. Found N results."
}

Consultas de ejemplo:

  1. Contar todas las páginas:

[:find (count ?p)
 :where [?p :node/title]]
  1. Búsqueda de texto sin distinción entre mayúsculas y minúsculas:

[:find ?string ?title
 :where
 [?b :block/string ?string]
 [(clojure.string/lower-case ?string) ?lower]
 [(clojure.string/includes? ?lower "search term")]
 [?b :block/page ?p]
 [?p :node/title ?title]]
  1. Buscar bloques modificados después de una fecha:

[:find ?block_ref ?string
 :in $ ?start_of_day
 :where
 [?b :edit/time ?time]
 [(> ?time ?start_of_day)]
 [?b :block/uid ?block_ref]
 [?b :block/string ?string]]

Consulte Roam_Research_Datalog_Cheatsheet.md para obtener más ejemplos de consultas y documentación de sintaxis.

Jerarquía del bloque de búsqueda

Navegar y buscar a través de las relaciones padre-hijo del bloque:

use_mcp_tool roam-research roam_search_hierarchy {
  "parent_uid": "optional-parent-block-uid",
  "child_uid": "optional-child-block-uid",
  "page_title_uid": "optional-page-title-or-uid",
  "max_depth": 3
}

Características:

  • Buscar hacia arriba o hacia abajo en la jerarquía de bloques

  • Buscar hijos de un bloque específico

  • Buscar padres de un bloque específico

  • Configurar la profundidad de búsqueda (1-10 niveles)

  • Filtrado de alcance de página opcional

  • Incluye información de profundidad para cada resultado.

Parámetros:

  • parent_uid : UID del bloque del que se buscarán los hijos (obligatorio si se busca hacia abajo)

  • child_uid : UID del bloque del que se buscarán los padres (obligatorio si se busca hacia arriba)

  • page_title_uid : Título o UID de la página donde buscar (opcional)

  • max_depth : Cuántos niveles de profundidad buscar (opcional, predeterminado: 1, máximo: 10)

Devoluciones:

{
  "success": true,
  "matches": [
    {
      "block_uid": "related-block-uid",
      "content": "Block content",
      "depth": 2,
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) as children/parents..."
}

Manejo de errores

El servidor proporciona un manejo integral de errores para escenarios comunes:

  • Errores de configuración:

    • Falta el token de API o el nombre del gráfico

    • Variables de entorno no válidas

  • Errores de API:

    • Errores de autenticación

    • Solicitudes no válidas

    • Operaciones fallidas

  • Errores específicos de la herramienta:

    • Página no encontrada (con búsqueda que no distingue entre mayúsculas y minúsculas)

    • Bloque no encontrado por coincidencia de cadena

    • Formato de rebajas no válido

    • Faltan parámetros requeridos

    • Estructura o contenido del esquema no válido

Cada respuesta de error incluye:

  • Código de error MCP estándar

  • Mensaje de error detallado

  • Sugerencias de resolución cuando corresponda

Desarrollo

Edificio

Para construir el servidor:

npm install
npm run build

Esto hará lo siguiente:

  1. Instalar todas las dependencias necesarias

  2. Compilar TypeScript a JavaScript

  3. Hacer que el archivo de salida sea ejecutable

También puede utilizar npm run watch durante el desarrollo para recompilar automáticamente cuando los archivos cambian.

Pruebas con MCP Inspector

El Inspector MCP es una herramienta que ayuda a probar y depurar servidores MCP. Para probar el servidor:

# Inspect with npx:
npx @modelcontextprotocol/inspector node build/index.js

Esto hará lo siguiente:

  1. Iniciar el servidor en modo inspector

  2. Proporcionar una interfaz interactiva para:

    • Enumere las herramientas y recursos disponibles

    • Ejecutar herramientas con parámetros personalizados

    • Ver las respuestas de la herramienta y el manejo de errores

Licencia

Licencia MIT

Available Tools

25 tools
roam_add_todoA

Add a list of todo items as individual blocks to today's daily page in Roam. Each item becomes its own actionable block with todo status. NOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use alias syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: todos (required), graph, write_key. Returns: success

roam_create_outlineA

Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels. To create a new page with an outline, use the roam_create_page tool instead. The outline parameter defines new blocks to be created. To nest content under an existing block, provide its UID or exact text in block_text_uid, and ensure the outline array contains only the child blocks with levels relative to that parent. Including the parent block's text in the outline array will create a duplicate block. Best for:

  • Adding supplementary structured content to existing pages

  • Creating temporary or working outlines (meeting notes, brainstorms)

  • Organizing thoughts or research under a specific topic

  • Breaking down subtopics or components of a larger concept Best for simpler, contiguous hierarchical content. For complex nesting (e.g., tables) or granular control over block placement, consider roam_process_batch_actions instead. API Usage Note: This tool performs verification queries after creation. For large outlines (10+ items) or when rate limits are a concern, consider using roam_process_batch_actions instead to minimize API calls.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: outline (required), graph, order, write_key, +2 more. Returns: success, page_uid, parent_uid, created_blocks

roam_create_pageA

Create a new standalone page in Roam with optional content, including structured outlines and tables, using explicit nesting levels and headings (H1-H3). This is the preferred method for creating a new page with an outline in a single step. Best for:

  • Creating foundational concept pages that other pages will link to/from

  • Establishing new topic areas that need their own namespace

  • Setting up reference materials or documentation

  • Making permanent collections of information

  • Creating pages with mixed text and table content in one call. Efficiency Tip: This tool batches page and content creation efficiently. For adding content to existing pages, use roam_process_batch_actions instead.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: title (required), graph, content, write_key. Returns: success, page_uid

roam_create_tableA

Create a table in Roam with specified headers and rows. This tool abstracts the complex nested structure that Roam tables require, making it much easier to create properly formatted tables.

Why use this tool:

  • Roam tables require precise nested block structures that are error-prone to create manually

  • Automatically handles the {{[[table]]}} container and nested column structure

  • Validates row/column consistency before execution

  • Converts empty cells to spaces (required by Roam)

Example: A table with headers ["", "Column A", "Column B"] and rows [{label: "Row 1", cells: ["A1", "B1"]}] creates a 2x3 table.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: rows (required), headers (required), parent_uid (required), graph, +2 more. Returns: error, success, uid_map, committed, +3 more

roam_datomic_queryA
Read-onlyIdempotent

Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. This provides direct access to Roam's query engine. Note: Roam graph is case-sensitive.

Optimal Use Cases for roam_datomic_query:

  • Advanced Filtering (including Regex): Use for scenarios requiring complex filtering, including regex matching on results post-query, which Datalog does not natively support for all data types. It can fetch broader results for client-side post-processing.

  • Highly Complex Boolean Logic: Ideal for intricate combinations of "AND", "OR", and "NOT" conditions across multiple terms or attributes.

  • Arbitrary Sorting Criteria: The go-to for highly customized sorting needs beyond default options.

  • Proximity Search: For advanced search capabilities involving proximity, which are difficult to implement efficiently with simpler tools.

List of some of Roam's data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text). Predicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=). Aggregates (distinct, count, sum, max, min, avg, limit). Tips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: query (required), graph, inputs, write_key, +3 more.

roam_fetch_blockA
Read-onlyIdempotent

Fetch a block by its UID with optional children (down to a specified depth) and/or ancestors (up to page root). Returns the block's UID, text, order, children array, and optionally an ancestors array with the chain to the page root.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: block_uid (required), depth, graph, write_key, +1 more.

roam_fetch_page_by_titleA
Read-onlyIdempotent

Fetch page by title. Returns content in the specified format.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: title (required), graph, format, write_key.

roam_fetch_page_full_viewA
Read-onlyIdempotent

Fetch a complete page view that mirrors what Roam Research shows in its UI: the page's own content, plus all linked references (backlinks) grouped by source page, each with their ancestor breadcrumb context and children expanded to the specified depth. Use this when you need the full picture of a page — both what is written on it and everything else in the graph that references it.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: title (required), graph, write_key, children_depth, +1 more.

roam_find_pages_modified_todayA
Read-onlyIdempotent

Find pages that have been modified today (since midnight), with pagination and sorting options.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, limit, offset, write_key, +1 more.

roam_get_guidelinesA
Read-onlyIdempotent

Retrieve this graph's user-defined agent conventions, read from the [[roam/agent guidelines]] page inside the graph (configurable per graph). These are the user's own rules — how they tag, how they name and namespace pages, what to never do, how they want your voice attributed.

Also returns roamSyntax: the rules whose violation destroys content — whole-page rewrites that delete, truncated previews written back as content, retyped block references, and the syntax that differs from standard markdown. These are returned on every call, including when the graph has no guidelines page, and they hold regardless of what the conventions say.

Call this ONCE per graph per session, before other tools, INCLUDING for reads: conventions change how results should be interpreted and presented, not just how content is written. Returns today's daily note title as orientation.

Distinct from roam_markdown_cheatsheet, which is the complete syntax reference — components, queries, embeds, tool selection. Call that when you need to look something up; this one you need before writing at all. Returns exists:false rather than failing when no page has been created.

Inputs: graph, write_key.

roam_get_subpagesA
Read-onlyIdempotent

Fetch all sub-pages (namespace children) of a given page prefix. Matches by page title prefix — pages titled "Prefix/Something" are sub-pages of "Prefix" and appear in the Hierarchy section of that page. This is namespace/title-prefix matching, distinct from roam_search_hierarchy which traverses block parent/child relationships. Optionally filter to only sub-pages containing a specific tag (e.g. filter active projects with filter_tag="active"), and optionally include each sub-page's full block content.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: prefix (required), graph, write_key, filter_tag, +1 more.

roam_import_markdownA

Import nested markdown content into Roam under a specific block. Can locate the parent block by UID (preferred) or by exact string match within a specific page. If a parent_string is provided and the block does not exist, it will be created. Returns a nested structure of the created blocks. API Usage Note: This tool fetches the full nested structure after import for verification. For large imports or when rate limits are a concern, consider using roam_process_batch_actions with pre-structured actions instead.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: content (required), graph, order, page_uid, +4 more. Returns: success, page_uid, parent_uid, created_blocks

roam_markdown_cheatsheetA
Read-onlyIdempotent

Provides the comprehensive Roam syntax reference. Covers: formatting, links & references (page refs, block refs, embeds including embed-children and embed-path), tags, dates, tasks, callouts, attributes, queries (native {{query}} with its clause rules and page-ref inheritance, plus :q Datalog tables with built-in rules), tables, kanban, mermaid diagrams (with theme support), advanced components (dropdowns, tooltips, templates, document mode, word-count), CSS tags (#.rm-E, #.rm-hide, etc.), anti-patterns, tool selection guide, and API efficiency tips.

IMPORTANT: Always load this cheatsheet before creating or updating Roam content. It prevents common syntax errors and guides tool selection.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, write_key.

roam_move_blockA
DestructiveIdempotent

Move a block to a new location (different parent or position). This is a convenience wrapper around roam_process_batch_actions for single block moves.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: block_uid (required), parent_uid (required), graph, order, +1 more. Returns: order, success, block_uid, new_parent_uid

roam_process_batch_actionsA
Destructive

RATE LIMIT EFFICIENT: This is the most API-efficient tool for multiple block operations. Combine all create/update/delete operations into a single call whenever possible. For intensive page updates or revisions, prefer this tool over multiple sequential calls.

Executes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Actions are executed in the provided order.

UID Placeholders for Nested Blocks: Use {{uid:name}} syntax for parent-child references within the same batch. The server generates proper random UIDs and returns a uid_map showing placeholder→UID mappings. Example: { uid: "{{uid:parent1}}", string: "Parent" } then { location: { "parent-uid": "{{uid:parent1}}" }, string: "Child" }. Response includes { success: true, uid_map: { "parent1": "Xk7mN2pQ9" } }.

For actions on existing blocks, a valid block UID is required. Note: Roam-flavored markdown, including block embedding with ((UID)) syntax, is supported within the string property for create-block and update-block actions. For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs. Tools like roam_fetch_page_by_title or other search tools can be used to retrieve these UIDs before executing batch actions. For simpler, sequential outlines, roam_create_outline is often more suitable.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: actions (required), graph, write_key. Returns: error, success, uid_map, committed, +2 more

roam_recallA
Read-onlyIdempotent

Retrieve all stored memories on page titled ROAM_MEMORIES_TAG, or tagged block content with the same name. Returns a combined, deduplicated list of memories. Optionally filter blocks with a specific tag and sort by creation date.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, sort_by, write_key, filter_tag.

roam_rememberA

Add a memory or piece of information to remember, stored on the daily page with ROAM_MEMORIES_TAG tag and optional categories (unless include_memories_tag is false). NOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use alias syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: memory (required), graph, heading, write_key, +3 more. Returns: success, block_uid, parent_uid

roam_rename_pageA
DestructiveIdempotent

Rename a page by changing its title. Identifies the page by current title or UID.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: new_title (required), uid, graph, old_title, +1 more. Returns: message, success

roam_search_block_refsA
Read-onlyIdempotent

Search for block references within a page or across the entire graph. Can search for references to a specific block, a page title, or find all block references.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, title, block_uid, write_key, +1 more.

roam_search_by_dateA
Read-onlyIdempotent

Search for blocks or pages based on creation or modification dates. Not for daily pages with ordinal date titles.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: type (required), scope (required), start_date (required), graph, +3 more.

roam_search_by_statusA
Read-onlyIdempotent

Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: status (required), graph, exclude, include, +2 more.

roam_search_by_textA
Read-onlyIdempotent

Search for blocks containing specific text across all pages or within a specific page. Use scope: "page_titles" to search for pages by namespace prefix (e.g., "Convention/" finds all pages starting with that prefix). This tool supports pagination via the limit and offset parameters. Pagination follows hidden-block filtering; block results use UID order and namespace results use title order.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: text (required), graph, limit, scope, +4 more.

roam_search_for_tagA
Read-onlyIdempotent

Search for blocks containing a specific tag. Use primary_tag for the tag to find, and optionally page_title_uid to limit search to a specific page. Supports pagination via limit and offset, applied after hidden-block filtering in UID order. Use this tool to search for memories tagged with the ROAM_MEMORIES_TAG.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: primary_tag (required), graph, limit, offset, +4 more.

roam_search_hierarchyA
Read-onlyIdempotent

Search for parent or child blocks in the block hierarchy. Can search up or down the hierarchy from a given block.

IMPORTANT: call roam_get_guidelines for this graph once per session before using this tool, reads included — conventions change how results are read, not just written.

Inputs: graph, child_uid, max_depth, write_key, +2 more.

roam_update_page_markdownA
DestructiveIdempotent

Update an existing page with new markdown content using smart diff. Preserves block UIDs where possible and generates minimal changes. This is ideal for:

  • Syncing external markdown files to Roam

  • AI-assisted content updates that preserve references

  • Batch content modifications without losing block references

⚠️ This REPLACES the page, it does not append. Any block your markdown does not account for is deleted. Pass the complete intended page, or use roam_process_batch_actions / roam_create_outline to change only part of one. Use dry_run: true to see the actions first.

How it works:

  1. Fetches existing page blocks

  2. Matches new content to existing blocks by text similarity

  3. Generates minimal create/update/move/delete operations

  4. Preserves UIDs for matched blocks (keeping references intact)

#.rm-hide / #.rm-private subtrees are excluded from the diff and left untouched — you cannot see them, so you cannot be asked to account for them. preserved_hidden reports how many, when any.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Inputs: title (required), markdown (required), graph, dry_run, +1 more. Returns: stats, actions, success, summary, +2 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools target distinct resources or actions, and the descriptions explicitly differentiate nearby tools such as roam_create_page vs. roam_create_outline vs. roam_process_batch_actions, and roam_fetch_page_by_title vs. roam_fetch_page_full_view. Some overlap remains, especially between namespace/page-title search and subpage retrieval, or between date search and modified-today search, but the boundaries are generally clear enough for tool selection.

    Naming Consistency4/5

    All tools share a consistent roam_ prefix and snake_case formatting, which makes the set predictable. The pattern is mostly roam_verb_noun, though a few names such as roam_markdown_cheatsheet and roam_datomic_query are noun-oriented rather than strict verb-object forms.

    Tool Count3/5

    With 25 tools, this is a heavy surface for an MCP server, even for a complex graph tool like Roam. The tools are mostly justified by distinct operations, but the set is large enough that an agent may need extra care to choose efficiently, especially across the many search and content-creation variants.

    Completeness4/5

    The surface covers most core Roam workflows: page creation, fetching, renaming, markdown updates, block fetching, moving, searching, batch block operations, tables, todos, memories, and references. Minor gaps remain, such as no explicit page deletion tool and block updates/deletes only being exposed through the broader batch-actions tool.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables Claude Desktop to read from and write to Roam Research graphs, allowing for retrieving page content, finding references, and adding blocks to existing or daily pages.
      4
      1
      -
    • A
      license
      A
      quality
      Not graded
      maintenance
      Enables AI assistants to interact with Roam Research graphs through comprehensive API access, supporting page/block operations, markdown import, search, memory storage, and complex batch actions for managing knowledge graphs.
      18
      404 npm
      -