Obsidian

Interactúa con bóvedas de Obsidian para leer, crear, editar y gestionar notas y etiquetas.

Documentación

Obsidian MCP

Un servidor local de Model Context Protocol que permite a asistentes compatibles con MCP leer y modificar de forma segura bóvedas de Obsidian configuradas explícitamente.

La versión 2 admite tanto MCP 2026-07-28 como clientes de la era 2025 de forma predeterminada, y requiere Node.js 22 o superior. Funciona directamente con archivos Markdown, por lo que no es necesario que Obsidian esté abierto. La compatibilidad con el protocolo heredado y con rutas posicionales de v1 está obsoleta e imprime instrucciones de migración exactas en stderr.

[!IMPORTANT] Los clientes MCP pueden invocar herramientas destructivas. Haz copias de seguridad de las bóvedas importantes, revisa los avisos de permisos del cliente y usa las precondiciones de revisión para notas editadas de forma concurrente.

Inicio rápido

Se requiere Node.js 22 o superior:

node --version # v22 or newer

Ejecuta con npx sin instalar el paquete globalmente. Fijar la versión principal recibe actualizaciones 2.x compatibles sin cruzar automáticamente una futura versión principal:

npx -y obsidian-mcp@2 serve --vault notes=/absolute/path/to/vault

Configura un cliente MCP para lanzar el mismo comando a través de stdio:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp@2", "serve", "--vault", "notes=/absolute/path/to/vault"]
    }
  }
}

Alternativamente, instala el paquete globalmente y usa "command": "obsidian-mcp" con los mismos argumentos comenzando en "serve":

npm install -g obsidian-mcp@2

Cada bóveda ya debe contener un directorio .obsidian y debe configurarse usando una ruta absoluta.

Ambas eras de protocolo se sirven desde las mismas definiciones de herramientas. Después de confirmar que tu cliente MCP negocia 2026-07-28, puedes optar por el modo solo-moderno añadiendo "--legacy", "reject" a args.

Los identificadores de bóveda usan letras minúsculas, dígitos, _ y -, deben comenzar con una letra y son los valores que los asistentes pasan a las herramientas. Se pueden configurar hasta diez bóvedas. Repite --vault para exponer más de una bóveda:

obsidian-mcp serve \
  --vault work=/Users/me/Documents/WorkVault \
  --vault personal=/Users/me/Documents/PersonalVault

Se permiten ubicaciones de red, extraíbles, ocultas y sincronizadas porque un --vault explícito se trata como autorización; las mismas protecciones de contención se aplican a todas las ubicaciones.

Principios de diseño

El acceso a las bóvedas está explícitamente permitido en el arranque del proceso.
Cada ruta de herramienta es relativa a la bóveda, se verifica por segmentos y está bloqueada contra enlaces simbólicos y estado reservado.
Las mutaciones de archivos se registran, se verifican conflictos, se reemplazan atómicamente y se revierten como una sola transacción.
El servidor nunca escucha en una interfaz de red ni envía telemetría.
stdout está reservado exclusivamente para mensajes MCP; los diagnósticos estructurados van a stderr.
Los resultados están limitados, paginados cuando corresponde y disponibles tanto como texto como contenido estructurado.

Herramientas

Herramienta	Propósito
`obsidian_list_vaults`	Lista los identificadores de bóveda configurados sin exponer rutas del host.
`obsidian_read_note`	Lee una página limitada de una nota y devuelve su SHA-256 `etag`.
`obsidian_create_note`	Crea una nota atómicamente sin sobrescribir.
`obsidian_edit_note`	Añade al final, al principio o reemplaza el contenido exacto de una nota.
`obsidian_delete_note`	Mueve una nota a la papelera de MCP o la elimina permanentemente con confirmación explícita.
`obsidian_move_note`	Mueve o renombra una nota y actualiza los backlinks inequívocos transaccionalmente.
`obsidian_create_directory`	Crea un directorio dentro de una bóveda transaccionalmente.
`obsidian_search_vault`	Busca contenido, nombres de archivo o etiquetas con paginación por cursor limitada.
`obsidian_add_tags`	Añade etiquetas a una o más notas atómicamente.
`obsidian_remove_tags`	Elimina etiquetas exactas, anidadas o seleccionadas por comodín atómicamente.
`obsidian_rename_tag`	Renombra una etiqueta en toda la bóveda atómicamente.
`obsidian_manage_tags`	Flujo de trabajo unificado de añadir/eliminar etiquetas usando la misma implementación.

Todos los esquemas son contratos estrictos de JSON Schema 2020-12 generados a partir de Zod. Los resultados de mutación incluyen un identificador de transacción; los fallos de herramientas devuelven isError: true con un código de error accionable.

Lectura y concurrencia

obsidian_read_note devuelve un etag. Pásalo como if_match para editar, mover o eliminar cuando evitar actualizaciones perdidas sea importante. Las operaciones de etiquetas por lotes aceptan un mapa expected_etags. Una nota modificada devuelve REVISION_CONFLICT en lugar de ser sobrescrita.

Las notas grandes se paginan usando un cursor opaco vinculado a la ruta y a etag. La búsqueda usa un cursor opaco vinculado a la consulta y las opciones. Las respuestas de texto de las herramientas están limitadas a 25 000 caracteres.

Eliminación y recuperación

La papelera es la opción predeterminada. Los bytes de las notas eliminadas y los metadatos se almacenan por separado bajo .obsidian-mcp/trash; los metadatos nunca se inyectan en la nota. La eliminación permanente requiere que confirm_path coincida exactamente con la ruta relativa canónica.

Las transacciones y las instantáneas de recuperación viven en .obsidian-mcp/transactions. Los datos completados se conservan durante 30 días y se depuran los más antiguos primero por encima de 1 GiB de forma predeterminada:

obsidian-mcp serve --vault work=/path \
  --recovery-days 14 \
  --recovery-max-bytes 536870912

Inspecciona o restaura una transacción completada mientras el servidor MCP está detenido:

obsidian-mcp recovery list --vault work=/path
obsidian-mcp recovery restore --vault work=/path --id <transaction-id>

La recuperación se niega a sobrescribir contenido modificado desde la transacción seleccionada. Las instantáneas de eliminación permanente se purgan después de la confirmación y no se pueden restaurar.

Seguridad de rutas y sistema de archivos

El servidor:

canoniza las raíces de bóveda configuradas y rechaza raíces duplicadas o anidadas;
rechaza rutas de herramientas absolutas, UNC, de unidad de Windows, NUL, con barra invertida, vacías y con segmentos de punto;
reserva .obsidian, .obsidian-mcp, .git, .backup y .trash del acceso de las herramientas;
verifica los destinos existentes y el ancestro existente más cercano para nuevos destinos;
rechaza enlaces simbólicos, junctions y rutas de reparse-point, y los omite durante los escaneos;
no ejecuta shell para la validación del sistema de archivos;
decodifica UTF-8 estrictamente y no reemplaza silenciosamente bytes inválidos.

El proceso necesita acceso de lectura y escritura a cada bóveda configurada. obsidian-mcp doctor --vault id=/path valida la preparación del arranque y el estado de recuperación.

Comportamiento de enlaces y etiquetas

Los movimientos reconocen Wikilinks de Obsidian, embeds, enlaces Markdown, alias, destinos codificados en URL, encabezados y anclas de bloque. Un enlace se reescribe solo cuando se resuelve inequívocamente a la nota de origen; los enlaces ambiguos se informan y se dejan sin cambios. La eliminación conserva los backlinks a menos que se solicite backlink_action: "mark_broken".

Las etiquetas siguen las reglas de Obsidian que no distinguen entre mayúsculas y minúsculas y admiten Unicode, emoji, _, -, / y etiquetas anidadas. Las etiquetas de frontmatter se escriben como listas YAML. El procesamiento de etiquetas en línea ignora código entre comillas/fenced y comentarios HTML. Los comodines usan un comparador limitado en lugar de expresiones regulares.

Desarrollo

npm ci
npm run typecheck
npm test
npm run build
npm run ci

Cada herramienta posee una definición tipada bajo src/tools/<tool>/index.ts; el pequeño registro en src/tools/index.ts aplica el registro MCP compartido y el comportamiento de respuesta. El comportamiento de sistema de archivos, transacciones, Markdown, enlaces y búsqueda vive en utilidades reutilizables. Una nueva herramienta debe usar VaultFs para cada ruta, TransactionManager para mutaciones, esquemas estrictos de entrada/salida, resultados estructurados, anotaciones y pruebas de seguridad/integración.

Consulta MIGRATING.md para la migración de 1.x y SECURITY.md para informar vulnerabilidades.

Los errores de arranque y las advertencias de compatibilidad se escriben solo en stderr con un código estable, el problema detectado, una corrección exacta, un paso de verificación y un enlace a la sección de migración correspondiente. Si el servidor no aparece, busca el código en los registros del cliente MCP y usa la referencia de diagnóstico.

Licencia

MIT