API REST local con MCP

Dale a tus scripts, extensiones de navegador y agentes de IA una línea directa hacia tu bóveda de Obsidian mediante una API REST segura y autenticada.

• Documentación interactiva de la API: https://coddingtonbear.github.io/obsidian-local-rest-api/

• Página de la comunidad de Obsidian: https://community.obsidian.md/plugins/obsidian-local-rest-api/

• Lo que puedes hacer

• Inicio rápido

  • API REST

  • Clientes MCP

    • Claude Code

    • Claude Desktop

    • Cursor

    • Otros clientes

• Resumen de la API

• Notas sobre parcheo

  • Modo de contenido sin procesar

• Apuntar a secciones específicas

• Búsqueda

• MCP (Model Context Protocol)

  • Revisiones del protocolo

  • Conectar un cliente

  • Herramientas disponibles

  • Recursos disponibles

• Extensiones de la API

  • API de extensión tipada

  • Extensiones conocidas

• Contribuir

• Créditos

Lo que puedes hacer

Accede a tu bóveda a través de la API REST o del servidor MCP integrado — ambas interfaces exponen las mismas capacidades principales, de modo que los scripts, las extensiones de navegador y los agentes de IA hablan el mismo idioma.

• Leer, crear, actualizar o eliminar notas — CRUD completo sobre cualquier archivo de tu bóveda, incluidos los archivos binarios

• Parchear secciones específicas quirúrgicamente — apunta a un encabezado, una referencia de bloque o una clave de frontmatter y añade, antepone, reemplaza, elimina o mueve solo esa sección sin tocar el resto del archivo

• Buscar en tu bóveda — búsqueda simple de texto completo o consultas estructuradas con JsonLogic sobre los metadatos de las notas (frontmatter, etiquetas, ruta, contenido)

• Acceder al archivo activo — lee o escribe la nota que esté abierta actualmente en Obsidian

• Listar y ejecutar comandos — dispara cualquier comando de Obsidian como si hubieras usado la paleta de comandos

• Consultar etiquetas — lista todas las etiquetas de tu bóveda con recuentos de uso

• Abrir archivos en Obsidian — dile a Obsidian que abra una nota específica en su interfaz

• Extender la API — otros plugins pueden registrar sus propias rutas mediante la interfaz de extensión de la API

Todas las solicitudes se sirven a través de HTTPS con un certificado autofirmado y están protegidas por autenticación mediante clave de API.

Related MCP server: Connect MCP

Inicio rápido

Después de instalar y habilitar el plugin, abre Configuración → Local REST API para encontrar tu clave de API y tu certificado.

API REST

# Check the server is running (no auth required)
curl -k https://127.0.0.1:27124/

# List files at the root of your vault
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/

# Read a note
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md

# Read a specific heading (URL-embedded target)
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Append a line to a specific heading (PATCH with a JSON instruction)
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"heading","target":["My Section"],"operation":"append","content":"New line of content"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

Para evitar advertencias de certificado, puedes descargar y confiar en el certificado desde https://127.0.0.1:27124/obsidian-local-rest-api.crt, o apuntar tu cliente HTTP directamente a él.

Clientes MCP

El servidor MCP se ejecuta en https://127.0.0.1:27124/mcp/ y requiere que proporciones tu token de portador para la autenticación mediante una cabecera Authorization (es decir, Authorization: Bearer <tu-clave-de-api>). Debido a que el plugin usa un certificado autofirmado, es posible que necesites confiar en el certificado en tu sistema operativo/cliente, o usar el endpoint HTTP simple en http://127.0.0.1:27123/mcp/ (actívalo en Configuración → Local REST API → Habilitar servidor HTTP).

Claude Code

Claude Code tiene soporte nativo para MCP HTTP. La forma más rápida de añadir el servidor es mediante la CLI:

claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ \
  --header "Authorization: Bearer <your-api-key>"

O añádelo manualmente a .mcp.json en la raíz de tu proyecto (con ámbito de proyecto) o configúralo a nivel de usuario mediante claude mcp add --scope user:

{
  "mcpServers": {
    "obsidian": {
      "type": "http",
      "url": "https://127.0.0.1:27124/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Claude Desktop

Claude Desktop no admite de forma nativa servidores MCP HTTP remotos, pero puedes conectarlo con mcp-remote (requiere Node.js). Añade lo siguiente a claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://127.0.0.1:27124/mcp/",
        "--header",
        "Authorization: Bearer <your-api-key>"
      ]
    }
  }
}

Reinicia Claude Desktop después de guardar el archivo.

Cursor

Cursor admite el transporte MCP HTTP Streamable. Añade lo siguiente a ~/.cursor/mcp.json (global) o .cursor/mcp.json (específico del proyecto):

{
  "mcpServers": {
    "obsidian": {
      "url": "https://127.0.0.1:27124/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Otros clientes

Cualquier cliente MCP que admita el transporte HTTP Streamable puede conectarse a https://127.0.0.1:27124/mcp/ con una cabecera Authorization: Bearer <tu-clave-de-api>. Consulta la documentación de tu cliente para conocer el formato de configuración exacto.

Resumen de la API

Para obtener detalles completos de solicitudes y respuestas, consulta la documentación interactiva.

Notas sobre parcheo

El método PATCH es una de las funciones más útiles de esta API. Te permite hacer ediciones específicas sin reescribir archivos completos.

Envía una instrucción JSON: una operación (replace, prepend, append o delete) aplicada a un ámbito (content, marker, markerAndContent o parent) de un objetivo — un encabezado (direccionado como una matriz de textos de encabezado desde el nivel superior hacia abajo), una referencia de bloque o una clave de frontmatter. La carga útil viaja en content (una cadena), value (JSON, para valores de frontmatter) o destination (un movimiento de encabezado):

# Replace the value of a frontmatter field
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"frontmatter","target":"status","operation":"replace","value":"done"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

Los niveles de encabezado dentro de una cadena content son relativos al objetivo (un # inicial se convierte en un hijo directo). Las advertencias (por ejemplo, un encabezado reajustado más allá del nivel 6) se devuelven como JSON codificado en porcentaje en la cabecera de respuesta Markdown-Patch-Warnings — decodifica con decodeURIComponent antes de analizarlo. Pasa ifMatch (la version de un mapa de documento) para concurrencia optimista.

Nota: El espacio en blanco es propiedad de la biblioteca — tu contenido se reduce a una forma canónica recortada (las líneas en blanco iniciales y finales no tienen significado), y la propia API suministra la línea en blanco dondequiera que el contenido insertado se enfrente al texto del cuerpo, de modo que un append o prepend siempre aterriza como su propio bloque y nunca se fusiona con un párrafo existente. Las líneas de encabezado, las líneas en blanco existentes y el estilo de espaciado de cada documento se conservan tal cual. Consulta la documentación interactiva para ver ejemplos prácticos.

Para continuar un bloque existente en lugar de comenzar uno nuevo — por ejemplo, extender una lista — añade within a una instrucción de encabezado: un índice que selecciona uno de los bloques de cuerpo de nivel superior de la sección (basado en 0 en orden de documento, negativo contando desde el final, de modo que -1 es el último bloque). Una edición con within se empalma literalmente, por lo que tú controlas la unión:

# Add an item to the last list under "Log" (the leading \n continues the block)
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"heading","target":["Log"],"within":-1,"operation":"append","content":"\n- new item"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

Con el ámbito markerAndContent, prepend/append insertan en su lugar un bloque nuevo junto al bloque indexado. Los índices son posicionales, así que lee primero el mapa de documento y combina la edición con ifMatch.

Modo de contenido sin procesar

Si tu cliente plantea markdown en el cuerpo de la solicitud (Shortcuts, Tasker, curl desde una plantilla), escapar ese contenido en JSON dentro de una instrucción es frágil. El modo de contenido sin procesar mueve los campos de la instrucción fuera del cuerpo — el objetivo en la URL (o en las cabeceras Target-Type/Target con un Markdown-Patch-Version: 2 explícito), la operación y las opciones en cabeceras — y el cuerpo es la carga útil sin procesar, sin necesidad de escape JSON:

# Append a templated line under a heading — no JSON escaping anywhere
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Operation: append" \
  -H "Content-Type: text/markdown" \
  --data "- $TEMPLATED_CONTENT" \
  https://127.0.0.1:27124/vault/notes/daily.md/heading/Log

Un cuerpo text/* es el portador de content, un cuerpo application/json es el portador de value, y ningún cuerpo no lleva nada (un delete, o un movimiento mediante una cabecera Destination). Las cabeceras Target-Scope, Within (el índice within de la instrucción como entero simple, p. ej. -1), Create-Target-If-Missing, Reject-If-Content-Preexists e If-Match completan la instrucción. Consulta la documentación interactiva para conocer las codificaciones de cabecera y todos los detalles.

¿Ya usas el formato PATCH anterior basado en cabeceras? Distribuía la instrucción en cabeceras de solicitud en lugar de un cuerpo JSON, y está obsoleto y se eliminará en 6.0. Aún funciona — envía Markdown-Patch-Version: 1 para volver a usarlo (la misma cabecera también selecciona el mapa de documento heredado unido con :: en GET), y las respuestas servidas por él llevan una cabecera Deprecation: true; sunset-version="6.0". Para actualizar, elimina esa cabecera y mueve cada cabecera al cuerpo JSON; la documentación interactiva tiene la tabla de mapeo campo por campo.

Consulta la documentación interactiva para conocer el esquema completo de instrucciones y las opciones.

Apuntar a secciones específicas

Puedes leer o escribir una parte específica de una nota — un encabezado, una referencia de bloque o un campo de frontmatter — sin obtener ni reemplazar todo el archivo. Esto funciona en solicitudes GET, PUT, POST y PATCH (para PATCH esto es modo de contenido sin procesar — añade una cabecera Operation).

Añade /<tipo-de-objetivo>/<objetivo> después del nombre del archivo. Cada nivel de encabezado anidado es su propio segmento de ruta, de modo que un encabezado cuyo texto contenga :: no necesita escape:

# Read the content under a specific heading
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Read a nested heading (one path segment per level)
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/Work/Meetings

# Read a frontmatter field
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/frontmatter/status

# Replace the content of a heading via PUT (heading levels are normalized for you)
curl -k -X PUT \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/markdown" \
  --data "Updated content" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Append to a heading via POST
curl -k -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/markdown" \
  --data "Appended content" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

Tipos de objetivo admitidos: heading, block, frontmatter.

En un GET, una cabecera Target-Scope selecciona qué parte del objetivo se devuelve, reflejando los ámbitos de PATCH: content (el predeterminado), marker (la etiqueta — el texto sin procesar de un encabezado, el id simple de un bloque, una clave de frontmatter) o markerAndContent (todo el nodo, exactamente en la forma que consume un replace de PATCH en ese ámbito — un subárbol de encabezado se lee de vuelta con su propia línea como # Título, niveles relativos a su padre):

# Read a whole section — heading line included — ready to edit and write back
curl -k -H "Authorization: Bearer <your-api-key>" \
  -H "Target-Scope: markerAndContent" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

Obsoleto: direccionamiento basado en cabeceras. Las versiones anteriores apuntaban a una sección con las cabeceras Target-Type, Target y Target-Delimiter (además de Target-Scope/Trim-Target-Whitespace). Esa forma está obsoleta y se eliminará en 6.0; solo se procesa si también envías Markdown-Patch-Version: 1 (las respuestas llevan entonces una cabecera Deprecation). Sin ella, proporcionar esas cabeceras de direccionamiento se rechaza con 400. Proporcionar tanto el direccionamiento por ruta de URL como el formulario de cabecera en una sola solicitud devuelve 422 Unprocessable Entity.

Búsqueda

POST /search/simple/?query=tus+términos ejecuta la búsqueda difusa integrada de Obsidian y devuelve nombres de archivo coincidentes con fragmentos de contexto puntuados.

POST /search/ acepta una expresión JsonLogic (tipo de contenido application/vnd.olrapi.jsonlogic+json) y la evalúa contra los metadatos de cada nota (frontmatter, etiquetas, ruta, contenido).

MCP (Model Context Protocol)

[!NOTE] Existen varios servidores MCP de terceros para Obsidian, pero ya no son necesarios: este plugin incluye un servidor MCP integrado que se ejecuta dentro de Obsidian y tiene acceso directo a los metadatos en vivo de tu bóveda, al archivo activo y a la paleta de comandos. Si actualmente usas un servidor de terceros, cambiar a este probablemente te dará mejores resultados.

El plugin incluye un servidor MCP integrado en /mcp/ para que los agentes de IA y los clientes compatibles con MCP puedan interactuar con tu bóveda sin tener que crear solicitudes HTTP manualmente.

Transporte: Streamable HTTP — se requiere autenticación con clave API.

Revisiones de protocolo

El endpoint sirve la revisión 2026-07-28 más las revisiones con sesión desde 2024-10-07 hasta 2025-11-25, eligiendo por solicitud, de modo que los clientes de cualquiera de ellas pueden compartirlo.

La revisión 2026-07-28 no tiene estado: no hay protocolo de inicio initialize ni sesión, por lo que el plugin no emite ni lee la cabecera Mcp-Session-Id. Cada solicitud lleva su propia versión de protocolo e identidad de cliente en params._meta, los repite en las cabeceras MCP-Protocol-Version, Mcp-Method y Mcp-Name, y se responde por sí sola. Los clientes pueden llamar a server/discover para conocer de antemano las revisiones y capacidades admitidas.

Los clientes que comienzan con una solicitud initialize reciben la revisión con sesión que negocian: el protocolo de inicio devuelve un Mcp-Session-Id, GET /mcp/ abre el flujo de notificaciones de esa sesión y DELETE /mcp/ la finaliza. Las sesiones existen solo en esta ruta, y son lo que mantiene honestas las capacidades listChanged del protocolo de inicio: cuando otro plugin registra o elimina una herramienta MCP, se notifica a cada sesión activa, mientras que los clientes 2026-07-28 se enteran a través de un flujo subscriptions/listen.

Conexión de un cliente

Conecta tu cliente MCP a https://127.0.0.1:27124/mcp/. La autenticación utiliza un token de portador: encuentra tu clave API en Configuración → Local REST API y pásala como:

Authorization: Bearer <your-api-key>

La sintaxis de configuración exacta varía según el cliente; consulta los ejemplos de Inicio rápido anteriores o la documentación de tu cliente para servidores MCP remotos con Streamable HTTP.

[!WARNING] Para conectarte al servidor MCP de forma segura, tu cliente debe confiar en el certificado autofirmado del plugin. Puedes descargarlo y confiar en él desde https://127.0.0.1:27124/obsidian-local-rest-api.crt, o configurar tu cliente para omitir la verificación TLS para 127.0.0.1.

Si no es posible confiar en un certificado autofirmado en tu entorno, puedes conectarte de forma insegura usando http://127.0.0.1:27123/mcp/ en lugar de https://127.0.0.1:27124/mcp/ si has habilitado el endpoint HTTP en Configuración → Local REST API → Habilitar servidor HTTP.

Herramientas disponibles

Recursos disponibles

Extensiones de API

Otros plugins pueden registrar sus propias rutas autenticadas, rutas públicas y herramientas MCP en el servidor de este plugin. Consulta Añadir tus propias rutas de API mediante una extensión para ver un tutorial.

API de extensión tipada

Instala este paquete como dependencia de desarrollo para obtener getAPI y los tipos de todo lo que devuelve:

npm install --save-dev obsidian-local-rest-api

Este paquete declara obsidian, zod y @types/express como dependencias entre pares, porque sus tipos se refieren a los tres: addRoute devuelve el IRoute de express, y addMcpTool acepta esquemas de zod. npm instala las dependencias entre pares por ti; si las fijas tú mismo, mantenlas resolubles. Sin ellas, TypeScript amplía silenciosamente esas posiciones a any en lugar de informar de un error, por lo que un proyecto que suprime el diagnóstico de tipos faltantes no recibe ninguna advertencia de que ha perdido la comprobación de tipos exactamente donde más importa.

import { getAPI, type LocalRestApiPublicApi } from "obsidian-local-rest-api";

const api: LocalRestApiPublicApi | undefined = getAPI(this.app, this.manifest, 2);

El punto de entrada del paquete es un pequeño módulo independiente: resuelve el plugin anfitrión en ejecución desde el registro de plugins de Obsidian en lugar de incluir el paquete del plugin en tu compilación. Pasar una versión de API de extensión (2 arriba) hace que getAPI lance ApiVersionUnsupportedError cuando el anfitrión instalado es más antiguo que la superficie que necesitas; omítelo para aceptar lo que esté instalado y detectar características tú mismo. getAPI devuelve undefined cuando el plugin no está instalado o aún no se ha cargado.

publicApi.d.ts se genera a partir de src/publicApi.ts, contra el cual se verifica la implementación en tiempo de compilación, por lo que los tipos publicados no pueden desviarse de lo que el plugin realmente ofrece.

Extensiones conocidas

• Periodic Notes: Añade soporte para notas periódicas

Contribuciones

Consulta CONTRIBUTING.md. Si quieres añadir funcionalidad sin modificar el núcleo, considera crear una extensión de API en su lugar: las extensiones se pueden desarrollar y publicar de forma independiente.

Créditos

Inspirado por el plugin advanced-uri de Vinzent03, con el objetivo de ampliar las opciones de automatización más allá de las limitaciones de los esquemas de URL personalizados.