Roam Research MCP Server

Accede y gestiona tu grafo de Roam Research a través de su API.

Documentación

Roam Research MCP + CLI

Introducción

Creé este proyecto para resolver un problema personal: quería gestionar mi grafo de Roam Research directamente desde Claude Code (y otros LLMs). Mientras construía el servidor Model Context Protocol (MCP) para dar a los agentes de IA acceso a mis notas, me di cuenta de que las herramientas subyacentes eran lo bastante potentes como para mantenerse por sí solas.

Lo que empezó como un backend para agentes de IA evolucionó hasta convertirse en una CLI independiente con todas las funciones. Ahora puedes usar las mismas capacidades de API directamente desde tu terminal — volcando contenido en Roam, buscando en tu grafo y gestionando tareas — sin necesidad de un LLM.

Ya sea que quieras darle superpoderes a Claude sobre tu base de conocimientos o simplemente quieras una CLI robusta para tus propios scripts, este proyecto te cubre.

Before and after: copy-pasting notes into Roam by hand, versus Claude and your terminal reading and writing the graph directly — install with npm i -g roam-research-mcp, then roam save "idea" or pipe with echo "Buy milk" | roam save --todo

En qué se diferencia del servidor MCP oficial de Roam

Roam Research incluye su propio servidor MCP y CLI (@roam-research/roam-mcp). Es una buena herramienta, y este proyecto no pretende sustituirla. Hablan con dos APIs diferentes de Roam, y de ahí se deriva todo lo demás.

	Este proyecto	Servidor `@roam-research/roam-mcp` oficial
Habla con	La API REST de backend de Roam (token de grafo + nombre de grafo)	La API HTTP local del escritorio de Roam
Necesita Roam en ejecución	No — funciona sin interfaz (headless)	Sí, la aplicación de escritorio debe estar abierta (hace deep-link para abrirla)
Dónde puede ejecutarse	En cualquier lugar: portátil, servidor, contenedor, CI	En la máquina que ejecuta Roam Desktop
Demonio compartido	Sí — `roam server` ejecuta un demonio HTTP para cada cliente	stdio por cliente
Multi-grafo	Variable de entorno `ROAM_GRAPHS`, con protección `write_key` para grafos elegidos	`~/.roam-tools.json`, un token por grafo
Grafos solo web	Funciona	Solo escritorio

Recurre al servidor oficial cuando quieras la vía compatible de Roam, o necesites cosas que solo la aplicación en ejecución puede hacer: controlar la interfaz del escritorio (abrir una página, leer la selección actual, manejar la barra lateral), búsqueda semántica con embeddings, sugerencias de enlaces, subida de archivos, comentarios, o invocar herramientas que hayan registrado las extensiones de Roam.

Recurre a este cuando Roam no esté en ejecución o no esté instalado — un servidor, un contenedor, un cron job, un paso de CI. O cuando quieras los extras que este proyecto ha ido acumulando: una CLI independiente completa con entrada por stdin, un demonio HTTP compartido con autenticación bearer opcional, un diff inteligente de páginas que conserva los UIDs de bloques (y por tanto tus referencias a bloques), operaciones por lotes con placeholders de UID para construir estructuras anidadas en una sola llamada, y herramientas de memoria para agentes.

Una omisión deliberada: no hay herramienta de borrado de páginas aquí. Roam no tiene un deshacer que pueda revertir un borrado masivo por API. El servidor oficial sí ofrece delete_page; este proyecto adopta la postura más conservadora.

Interoperan entre sí

Los dos servidores comparten convenciones a propósito, de modo que ejecutar ambos no te cuesta nada:

[[roam/agent guidelines]] — ambos leen la misma página para tus convenciones. Escríbelas una vez; ambos las respetan. Consulta Directrices del agente.
#.rm-hide / #.rm-private — ambos excluyen bloques etiquetados del contenido dirigido a la IA. Etiqueta una vez, oculto en ambos. Consulta Ocultar contenido a la IA.

CLI independiente: `roam`

La CLI de roam te permite interactuar con tu grafo directamente desde el terminal. Admite entrada estándar (stdin) mediante tubería (piping) para todos los comandos de creación y recuperación de contenido, lo que la hace perfecta para flujos de trabajo automatizados.

Ejemplos rápidos

# Save a quick thought to your daily page
roam save "Idea: A CLI for Roam would be cool"

# Pipe content from a file to a new page
cat meeting_notes.md | roam save --title "Meeting: Project Alpha"

# Create a TODO item on today's daily page
echo "Buy milk" | roam save --todo

# Prepend to top of page (newest-first ordering)
roam save -p "Changelog" --order first "v2.18.0 release"

# Search your graph and pipe results to another tool
roam search "important" --json | jq .

# Search for pages by namespace prefix
roam search --namespace "Convention"    # Finds all Convention/* pages

# Fetch a page by title
roam get "Roam Research"

# Fetch daily pages using any date format (auto-normalized)
roam get today                          # Today's daily page
roam get 2026-03-21                     # ISO date → "March 21st, 2026"
roam get "03/21/2026"                   # US date → "March 21st, 2026"
roam get "March 21"                     # Named (assumes current year)

# Fetch a block with ancestors (parent chain to page root)
roam get abc123def -a              # Block + children + ancestors
roam get abc123def -a -d 0         # Ancestors only, no children

# Fetch page by UID or Roam URL
roam get page abc123def
roam get page "https://roamresearch.com/#/app/my-graph/page/abc123def"

# Sort and group results
roam get --tag Project --sort created --group-by tag

# Find references (backlinks) to a page
roam refs "Project Alpha"

# Update a block (e.g., toggle TODO status)
roam update ((block-uid)) --todo

# Multi-graph: read from a specific graph
roam get "Page Title" -g work

# Multi-graph: write to a protected graph
roam save "Note" -g work --write-key "$ROAM_SYSTEM_WRITE_KEY"

Comandos disponibles: get, search, save, refs, update, batch, rename, status, server. Ejecuta roam <command> --help para ver los detalles de cualquier comando.

Instalación

npm install -g roam-research-mcp
# The 'roam' command is now available globally

Herramientas del servidor MCP

El servidor MCP expone estas herramientas a los asistentes de IA (como Claude), permitiéndoles leer, escribir y organizar tu grafo de Roam de forma inteligente.

Soporte multi-grafo: Todas las herramientas aceptan parámetros opcionales graph y write_key. Usa graph para apuntar a un grafo específico de tu configuración ROAM_GRAPHS, y write_key para operaciones de escritura en grafos protegidos.

Nombre de la herramienta	Descripción
`roam_fetch_page_by_title`	Obtener el contenido de una página por título.
`roam_fetch_page_full_view`	Obtener el contenido de una página más todas las referencias enlazadas con contexto de breadcrumb e hijos.
`roam_fetch_block`	Obtener un bloque por UID con hijos opcionales (profundidad) y/o ancestros (hasta la raíz de la página).
`roam_create_page`	Crear páginas nuevas, opcionalmente con contenido mixto de texto y tablas.
`roam_update_page_markdown`	Actualizar una página usando diff inteligente (preserva los UIDs de bloques).
`roam_get_subpages`	Listar subpáginas bajo un prefijo de espacio de nombres (p. ej., "Proyecto/") con filtro de etiquetas opcional.
`roam_search_by_text`	Búsqueda de texto completo en todo el grafo o dentro de páginas concretas. Admite búsqueda por prefijo de espacio de nombres para títulos de página.
`roam_search_block_refs`	Encontrar bloques que referencian una página, etiqueta o UID de bloque.
`roam_search_by_status`	Encontrar elementos TODO o DONE.
`roam_search_for_tag`	Encontrar bloques que contienen etiquetas específicas (admite exclusión).
`roam_search_by_date`	Encontrar bloques/páginas por fecha de creación o modificación.
`roam_find_pages_modified_today`	Listar páginas modificadas desde medianoche.
`roam_add_todo`	Añadir elementos TODO a la página diaria de hoy.
`roam_create_table`	Crear tablas de Roam con el formato correcto.
`roam_create_outline`	Crear esquemas jerárquicos.
`roam_process_batch_actions`	Ejecutar múltiples acciones de bajo nivel (crear, mover, actualizar, borrar) en un solo lote.
`roam_move_block`	Mover un bloque a una nueva posición o padre.
`roam_remember` / `roam_recall`	Herramientas especializadas para la gestión de memoria de IA dentro de Roam.
`roam_datomic_query`	Ejecutar consultas Datalog en bruto para filtrado avanzado.
`roam_markdown_cheatsheet`	Recuperar la referencia de markdown con el sabor de Roam.
`roam_get_guidelines`	Recuperar las convenciones de agente definidas por el usuario para este grafo.

Resultados estructurados de las herramientas de escritura (v3.0.0+)

Las diez herramientas de escritura declaran un outputSchema y devuelven structuredContent — un objeto validado — junto con el texto habitual. Un cliente puede leer page_uid, uid_map o success directamente en lugar de buscar el JSON dentro de una cadena, lo que hace más fiable el encadenamiento de llamadas:

// roam_process_batch_actions
{ "success": true, "uid_map": { "parent1": "Xk7mN2pQ9" },
  "validation_passed": true, "actions_attempted": 4 }

Tres cosas que conviene saber:

No se ha quitado nada. El canal de texto no cambia, así que un cliente que ignore structuredContent se comporta exactamente como antes.
Las herramientas de lectura deliberadamente no tienen ni lo uno ni lo otro. Ya serializan todo su resultado en el canal de texto, así que un esquema solo duplicaría la carga útil.
Estos campos son solo aditivos. Algunos clientes validan las respuestas en vivo contra una lista de herramientas en caché, así que un campo se añadirá o marcará como obsoleto — nunca se renombrará ni eliminará fuera de una versión mayor.

Actualización desde 2.x: se renombraron tres campos de resultado de escritura — uid → page_uid (roam_create_page), created_uids → created_blocks (roam_create_outline, roam_import_markdown) y preservedUids → preserved_uids (roam_update_page_markdown). Esto solo afecta al código que lee esos nombres; si usas el servidor a través de un asistente de IA, nada cambia. Consulta el registro de cambios para ver el motivo.

Directrices del agente (por grafo)

roam_get_guidelines lee una página dentro del grafo — [[roam/agent guidelines]] por defecto — con tus propias convenciones: cómo etiquetas, cómo organizas los espacios de nombres de las páginas, qué no debe hacer nunca un agente. El servidor MCP oficial de Roam lee el mismo título de página, así que una sola página sirve para ambos.

Esto es distinto de CUSTOM_INSTRUCTIONS_PATH, y ambos se complementan:

	`CUSTOM_INSTRUCTIONS_PATH`	`[[roam/agent guidelines]]`
Vive en	un archivo en disco	una página del grafo
Alcance	a nivel de servidor, todos los grafos	por grafo
Cómo cambiarlo	edita el archivo, reinicia el servidor	edita la página
Responde a	cómo escribir markdown de Roam	cómo quiere este usuario que se gestione este grafo

Solo tienes que crear la página. Sin ninguna configuración, roam_get_guidelines lee [[roam/agent guidelines]] — el mismo título que lee el servidor de Roam, así que escribirlo una vez hace que ambos lo respeten. Crear una página con ese título exacto con espacio de nombres es la forma de activarlo; no se lee nada del grafo salvo que un agente llame explícitamente a la herramienta.

Si la página no existe, la herramienta devuelve exists: false en lugar de fallar, así que siempre es seguro llamarla.

También devuelve las reglas que no dependen de ti

Junto con tus convenciones, cada respuesta de roam_get_guidelines incluye un campo roamSyntax: la breve lista de cosas que destruyen contenido — roam_update_page_markdown borrando todos los bloques que tu markdown omite, vistas previas truncadas de structure escritas como si fueran contenido, referencias de bloques reescritas como texto plano — además de una advertencia de que las lecturas excluyen silenciosamente los subárboles #.rm-hide, y los pocos casos en los que el markdown de Roam invierte el markdown estándar.

Dos razones por las que va aquí y no en la chuleta (cheatsheet): llega a todos los clientes, incluido uno que nunca llame a roam_markdown_cheatsheet; y se devuelve incluso cuando un grafo no tiene página de directrices, que es exactamente el caso en el que un agente tiene menos contexto. La estratificación es deliberada: tus convenciones deciden el estilo, roamSyntax decide la seguridad de los datos. Ninguna convención puede hacer que una vista previa truncada esté completa.

La referencia de sintaxis completa — componentes, consultas, embeds, selección de herramientas — está en roam_markdown_cheatsheet. roamSyntax son unas ~800 tokens y está limitada deliberadamente.

Cada grafo puede apuntar a una página distinta, o desactivarlo:

ROAM_GRAPHS='{
  "personal": {"token": "...", "graph": "..."},
  "work":     {"token": "...", "graph": "...", "guidelinesPage": "work/agent rules"},
  "private":  {"token": "...", "graph": "...", "guidelinesPage": false}
}'
ROAM_GUIDELINES_PAGE='team/agent guidelines'   # change the default for every graph

El orden de resolución es guidelinesPage por grafo → ROAM_GUIDELINES_PAGE → roam/agent guidelines. Arriba: personal usa la anulación por variable de entorno, work usa su propia página, y private tiene las directrices completamente desactivadas. Solo un false explícito lo desactiva — un valor sin definir nunca lo hace.

Los resultados se guardan en caché durante 30 segundos — una edición en la página surte efecto sin reiniciar. Una plantilla inicial está en .roam/agent-guidelines.template.md.

Ten en cuenta que las directrices se leen a través de la ruta normal de página, así que los bloques etiquetados con #.rm-hide / #.rm-private también se excluyen de ellas — ver más abajo.

Ocultar contenido a la IA

Los bloques etiquetados con #.rm-hide o #.rm-private — y todo lo anidado bajo ellos — se omiten del contenido que devuelven estas herramientas. Funcionan tanto la forma de hashtag (#.rm-hide, #[[.rm-hide]]) como la de enlace ([[.rm-hide]]). .rm-private es la etiqueta existente de Roam para "oculto a otros usuarios"; .rm-hide oculta específicamente a la IA.

Esto sigue la misma convención que el servidor MCP oficial de Roam, así que un bloque etiquetado para uno queda oculto para el otro.

Se aplica a: roam_fetch_page_by_title, roam_fetch_block, roam_fetch_page_full_view, roam_get_subpages, roam_search_by_text, roam_search_for_tag, roam_search_by_status, roam_search_block_refs, roam_search_hierarchy, roam_search_by_date. Los bloques ocultos también se excluyen del diff de reescritura de página, que es lo que evita que se eliminen por estar ausentes del markdown que el agente no pudo haber escrito. roam_update_page_markdown (y roam save --update) reemplaza una página con lo que le des, eliminando lo que tu markdown omita — por lo que su línea base se poda con este mismo filtro, según la regla de que la línea base de la que un diff elimina debe ser la misma página que el llamador tenía permitido leer. Reporta preserved_hidden cuando protegió algo. El contenido se conserva; el orden exacto relativo a los hermanos visibles puede cambiar. Esto era un error real de pérdida de datos antes de la corrección — ver el registro de cambios.

Este es un filtro de conveniencia, no una garantía de seguridad. roam_datomic_query lee la base de datos directamente y deliberadamente no lo aplica, por lo que un agente capaz aún puede sacar a la luz bloques ocultos a través de Datalog crudo. Trata estas etiquetas como "mantenerlo fuera del camino de la IA", no "mantenerlo en secreto".

La coincidencia de etiquetas no distingue mayúsculas y minúsculas, y solo coinciden etiquetas exactas — #.rm-hidden y #.rm-highlight se dejan solas. El conjunto de UIDs ocultos se almacena en caché durante 30 segundos, por lo que un bloque etiquetado justo ahora puede permanecer visible hasta ese tiempo.

Configuración

Variables de Entorno

Modo de Grafo Único

Para un solo grafo de Roam, establece estos en tu entorno o en un archivo .env:

ROAM_API_TOKEN=your-api-token
ROAM_GRAPH_NAME=your-graph-name

Modo Multi-Grafo (v2.0+)

Conecta a múltiples grafos de Roam desde una única instancia del servidor:

ROAM_GRAPHS='{
  "personal": {"token": "token-1", "graph": "personal-db", "memoriesTag": "#[[Personal Memories]]"},
  "work": {"token": "token-2", "graph": "work-db", "protected": true, "memoriesTag": "#[[Work Memories]]"},
  "research": {"token": "token-3", "graph": "research-db"}
}'
ROAM_DEFAULT_GRAPH=personal
ROAM_SYSTEM_WRITE_KEY=your-secret-key

Opciones de Configuración del Grafo:

Propiedad	Requerido	Descripción
`token`	Sí	Token de API de Roam para este grafo
`graph`	Sí	Nombre del grafo/identificador de base de datos
`protected`	No	Si `true`, las escrituras requieren confirmación de `ROAM_SYSTEM_WRITE_KEY` — excepto en el grafo predeterminado, ver abajo
`memoriesTag`	No	Etiqueta para `roam_remember`/`roam_recall` (anula el valor predeterminado global)

Dos tipos de control de acceso (y en qué se diferencian)

El servidor tiene dos candados independientes. Son fáciles de confundir porque ambos son "llaves" — aquí está la versión simple (ambos son opcionales y desactivados por defecto):

	Token portador — `HTTP_AUTH_TOKEN`	Clave de escritura — `ROAM_SYSTEM_WRITE_KEY`
En una frase	La llave de la puerta principal	El pestillo de una caja fuerte interior
Controla	Quién puede llegar al servidor en absoluto	Si se permite una escritura a un grafo `protected`
Cubre	Todo — lecturas y escrituras, todos los grafos	Solo escrituras, y solo a grafos marcados `protected`
¿Protege la lectura?	Sí	No
Cuándo lo necesitas	Solo si el servidor es accesible más allá de tu propia máquina (p. ej. `-H 0.0.0.0`)	Siempre que quieras una protección contra ediciones accidentales en grafos importantes
Cómo se envía	Cabecera HTTP: `Authorization: Bearer <token>`	Un argumento `write_key` en herramientas de escritura / comandos CLI

Piensa en una casa: el token portador bloquea la puerta principal (mantiene a los extraños completamente fuera), y la clave de escritura bloquea una caja fuerte interior (incluso alguien ya en la casa la necesita para cambiar lo que hay en la caja fuerte). En tu propia máquina vinculada a 127.0.0.1, la puerta principal da a una pared — no necesitas el token portador allí. La clave de escritura sigue siendo útil localmente como protección de "¿estás seguro?", porque Roam no tiene deshacer.

Entonces: para marcar un grafo como que necesita la clave de escritura, establece protected: true en él y configura ROAM_SYSTEM_WRITE_KEY; los llamadores entonces pasan un write_key coincidente para cualquier escritura a ese grafo.

⚠️ protected no hace nada en tu grafo predeterminado. Las escrituras a cualquier grafo que ROAM_DEFAULT_GRAPH nombre siempre están permitidas, antes de que se consulte protected — la bandera protege los grafos a los que tienes que pedir por nombre, con el razonamiento de que alcanzar un grafo no predeterminado es el acto deliberado que vale la pena confirmar. Si quieres que un grafo esté protegido contra escritura, no debe ser tu predeterminado.

Opcional:

ROAM_MEMORIES_TAG: Etiqueta predeterminada para roam_remember/roam_recall (respaldo cuando no se establece memoriesTag por grafo).
HTTP_STREAM_PORT: Puerto para el transporte HTTP Stream (por defecto 8088). Solo modo --server — el modo stdio no abre socket, por lo que se ignora allí.
HTTP_STREAM_HOST: Host al que vincular el transporte HTTP (por defecto 127.0.0.1, solo loopback). Solo modo --server. Establece a 0.0.0.0 para exponer en la LAN, y establece HTTP_AUTH_TOKEN cuando lo hagas.
HTTP_AUTH_TOKEN: Token portador opcional que bloquea todo el endpoint HTTP. Sin establecer = abierto (bien para loopback). Cuando se establece, cada solicitud MCP debe enviar Authorization: Bearer <token> (GET /health permanece abierto). Úsalo siempre que vincules más allá de 127.0.0.1. Diferente de ROAM_SYSTEM_WRITE_KEY — ver Dos tipos de control de acceso.

Ejecutando el Servidor

1. Modo Predeterminado (stdio) Mejor para integración local (p. ej., Claude Desktop, extensiones de IDE). El cliente MCP lanza el proceso por sesión y se comunica con él a través de stdin/stdout. No se abre ningún puerto — nada sobre MCP sobre stdio necesita uno.

Antes de 3.1.0 este modo también abría un listener HTTP, y lo vinculaba a cada interfaz. Si estabas usando ese endpoint, ejecuta un daemon --server en su lugar; ver abajo.

npx roam-research-mcp

2. Modo de Servidor Compartido (--server) Mejor para un daemon único de larga duración, solo HTTP, que comparten múltiples clientes MCP — en lugar de que cada sesión genere su propio subproceso. Esto ahorra memoria y da a los clientes una URL estable.

HTTP_STREAM_PORT=8088 npx roam-research-mcp --server

O adminístralo a través de la CLI roam, que añade inicio/parada/estado/registros:

roam server start            # start the shared daemon in the background
roam server start -H 0.0.0.0 # expose on the LAN (no transport auth!)
roam server status           # is it up? version, graphs, active sessions
roam server logs -f          # follow the log
roam server stop             # stop a CLI-started daemon

roam server status funciona sin importar cómo se lanzó el daemon (sondea /health), por lo que también informa de un daemon iniciado por una unidad LaunchAgent/systemd. El estado (pidfile + log) vive en ~/.roam/ (anula con ROAM_HOME).

Los dos modos son mutuamente excluyentes, y cada uno abre exactamente un transporte: el modo stdio habla stdio y no vincula nada, --server habla HTTP y no lee stdin. En modo --server el servidor:

ejecuta solo HTTP (sin transporte stdio),
vincula el exacto HTTP_STREAM_PORT en HTTP_STREAM_HOST y sale con código no cero si el puerto está ocupado (sin deriva silenciosa — un daemon compartido debe mantener una URL estable),
expone GET /health → {"status":"ok", ...} para comprobaciones de actividad.

Apunta los clientes MCP a él con una configuración de transporte HTTP:

{
  "mcpServers": {
    "roam-research-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8088/mcp"
    }
  }
}

Las variables de entorno (tokens, grafos) viven con el proceso del servidor, no con la configuración del cliente.

Asegurando un servidor expuesto (dos capas): Si vinculas más allá de loopback (-H 0.0.0.0), añade el candado perimetral:

HTTP_AUTH_TOKEN=$(openssl rand -hex 32) roam server start -H 0.0.0.0

Los clientes entonces envían el token como cabecera:

{
  "mcpServers": {
    "roam-research-mcp": {
      "type": "http",
      "url": "http://<host>:8088/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Mantén ambos — hacen trabajos diferentes (ver Dos tipos de control de acceso arriba): el token portador controla quién puede conectarse, la clave de escritura solo protege escrituras a grafos protegidos.

⚠️ La clave de escritura no es un sustituto del token portador. En un servidor expuesto sin HTTP_AUTH_TOKEN, cualquiera en la red aún puede leer cada grafo (y escribir en los no protegidos). Para cualquier cosa más allá de loopback, establece HTTP_AUTH_TOKEN.

Manteniéndolo en ejecución (LaunchAgent de macOS): Crea ~/Library/LaunchAgents/com.example.roam-mcp.plist con RunAtLoad + KeepAlive, tus variables de entorno bajo EnvironmentVariables, y --server como la última entrada de ProgramArguments. Mantén StandardOutPath/StandardErrorPath en una ruta local (p. ej. ~/Library/Logs/), luego:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.roam-mcp.plist
curl -s http://127.0.0.1:8088/health   # verify

3. Docker

docker run -p 8088:8088 --env-file .env roam-research-mcp --server

Configuración en LLMs

Claude Desktop / Cline:

Añade a tu archivo de configuración MCP (p. ej., ~/Library/Application Support/Claude/claude_desktop_config.json):

Fijando la versión. npx -y roam-research-mcp obtiene la última versión cada vez que tu cliente inicia el servidor, por lo que una nueva versión mayor llega sin aviso. Fija la mayor para decidir tú mismo cuándo moverte:

args Obtienes
["-y", "roam-research-mcp"] La última, siempre — incluyendo la próxima mayor
["-y", "roam-research-mcp@3"] Solo 3.x; las mayores necesitan una edición aquí
["-y", "roam-research-mcp@3.0.0"] Exactamente esta compilación

Fijar la mayor es el valor predeterminado sensato: aún obtienes correcciones y nuevas herramientas, pero un cambio disruptivo se convierte en algo en lo que optas. Los ejemplos a continuación permanecen sin fijar para coincidir con lo que la mayoría pega primero.

`args`	Obtienes
`["-y", "roam-research-mcp"]`	La última, siempre — incluyendo la próxima mayor
`["-y", "roam-research-mcp@3"]`	Solo 3.x; las mayores necesitan una edición aquí
`["-y", "roam-research-mcp@3.0.0"]`	Exactamente esta compilación

Grafo Único:

{
  "mcpServers": {
    "roam-research": {
      "command": "npx",
      "args": ["-y", "roam-research-mcp"],
      "env": {
        "ROAM_API_TOKEN": "your-token",
        "ROAM_GRAPH_NAME": "your-graph"
      }
    }
  }
}

Multi-Grafo:

{
  "mcpServers": {
    "roam-research": {
      "command": "npx",
      "args": ["-y", "roam-research-mcp"],
      "env": {
        "ROAM_GRAPHS": "{\"personal\":{\"token\":\"token-1\",\"graph\":\"personal-db\",\"memoriesTag\":\"#[[Memories]]\"},\"work\":{\"token\":\"token-2\",\"graph\":\"work-db\",\"protected\":true}}",
        "ROAM_DEFAULT_GRAPH": "personal",
        "ROAM_SYSTEM_WRITE_KEY": "your-secret-key"
      }
    }
  }
}

Analizador de Bloques de Consulta (v2.11.0+)

Una utilidad para analizar y ejecutar bloques de consulta de Roam programáticamente. Convierte la sintaxis {{[[query]]: ...}} en consultas Datalog.

Cláusulas Soportadas

Cláusula	Sintaxis	Descripción
Referencia de página	`[[page]]`	Bloques que referencian una página
Referencia de bloque	`((uid))`	Bloques que referencian un bloque
`and`	`{and: [[a]] [[b]]}`	Todas las condiciones deben coincidir
`or`	`{or: [[a]] [[b]]}`	Cualquier condición coincide
`not`	`{not: [[tag]]}`	Excluir coincidencias
`between`	`{between: [[date1]] [[date2]]}`	Filtro de rango de fechas
`search`	`{search: text}`	Búsqueda de texto completo
`daily notes`	`{daily notes: }`	Solo páginas de notas diarias
`by`	`{by: [[User]]}`	Creado o editado por usuario
`created by`	`{created by: [[User]]}`	Creado por usuario
`edited by`	`{edited by: User}`	Editado por usuario

Fechas Relativas

La cláusula between soporta fechas relativas: today, yesterday, last week, last month, this year, 7 days ago, 2 months ago, etc.

Uso

import { QueryExecutor } from 'roam-research-mcp/query';

const executor = new QueryExecutor(graph);

// Execute a query
const results = await executor.execute(
  '{{[[query]]: "My Query" {and: [[Project]] {between: [[last month]] [[today]]}}}}'
);

// Parse without executing (for debugging)
const { name, query } = QueryParser.parseWithName(queryBlock);

Funciones de Utilidad

import { isQueryBlock, extractQueryBlocks } from 'roam-research-mcp/query';

// Detect if text is a query block
isQueryBlock('{{[[query]]: [[tag]]}}'); // true

// Extract all query blocks from a string
extractQueryBlocks(pageContent); // ['{{[[query]]: ...}}', ...]

Soporte

Si este proyecto te ayuda a gestionar tu base de conocimiento o a construir agentes geniales, ¡considera invitarme a un café! Ayuda a que las actualizaciones sigan llegando.

https://paypal.me/2b3/5

Licencia

Licencia MIT - Creado por Ian Shen.