obsidian-cli-mcp

Un servidor MCP que otorga a Claude y otros clientes MCP control total sobre una bóveda de Obsidian en ejecución a través de la CLI oficial de Obsidian (Obsidian 1.12+), con lecturas rápidas directas del sistema de archivos cuando la corrección lo permite.

Proyecto complementario de things-for-mac-mcp.

¿Qué lo hace diferente?

La mayoría de los servidores MCP de Obsidian se comunican con un plugin REST de la comunidad o leen directamente la carpeta de la bóveda. El primero requiere instalar y confiar en un plugin. El segundo rompe silenciosamente los wikilinks en el momento en que mueve o renombra un archivo, porque solo Obsidian conoce cada enlace, alias y embed que apunta a él.

Este servidor enruta cada operación según su capacidad:

La arquitectura refleja exactamente la de su proyecto hermano:

La regla detrás de la división: las lecturas masivas van al sistema de archivos porque necesitan rendimiento, y cualquier cosa que mueva, renombre, elimine o dependa de la resolución de enlaces o del estado de la aplicación pasa por la CLI porque necesita el conocimiento de Obsidian. El adaptador del sistema de archivos estructuralmente no puede mutar la bóveda, no exporta ninguna función de escritura.

Requisitos

• macOS, Windows o Linux de escritorio con Obsidian 1.12 o posterior

• La CLI de Obsidian habilitada: Obsidian, Configuración, General, Interfaz de línea de comandos

• Obsidian debe estar en ejecución. La CLI es un cliente de la aplicación, no un binario independiente. Esto es solo para escritorio, no se admite móvil.

• Node.js 18 o posterior

Instalación

git clone https://github.com/jabaho9523/obsidian-cli-mcp.git
cd obsidian-cli-mcp
npm install
npm run build

Conectar a un cliente MCP

Claude (Desktop / Code)

Añadir a claude_desktop_config.json (Claude Desktop) o ejecutar claude mcp add (Claude Code):

{
  "mcpServers": {
    "obsidian": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/obsidian-cli-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT": "YourVaultName"
      }
    }
  }
}

Usa la ruta absoluta a node, no la palabra simple. Las aplicaciones lanzadas desde la GUI no heredan el PATH de tu shell, por lo que "command": "node" falla silenciosamente en muchos clientes. Encuentra la tuya con which node.

Establece OBSIDIAN_VAULT si tienes más de una bóveda. De lo contrario, la CLI apunta a la bóveda que estuvo enfocada por última vez, lo cual es una propiedad terrible para escrituras automatizadas. Con una sola bóveda, el servidor la fija automáticamente al inicio.

Configuración

Barreras de protección

Tres niveles, aplicados antes de que el binario se ejecute:

• Nivel 1, gratuito: lecturas, búsquedas y escrituras aditivas (create_note, append_note, append_daily, set_property, update_task, capture).

• Nivel 2, requiere confirm: true en la llamada a la herramienta: delete_note, move_note, rename_note, remove_property, run_obsidian_command, y a través del paso directo: history:restore, publish:*, plugin:enable/disable/reload, theme:*, snippet:*, sync, sync:restore, reload, template:insert, workspace:save/delete. Cualquier llamada que lleve una bandera overwrite o permanent también se eleva al nivel 2.

• Nivel 3, bloqueado a menos que el servidor se ejecute con OBSIDIAN_MCP_ALLOW_DANGEROUS=1: eval, restart, plugin:install, plugin:uninstall, plugins:restrict, devtools, dev:cdp, dev:debug, dev:mobile, y delete_note con permanent: true.

Una nota honesta sobre qué son estas barreras. El nivel 2 es un obstáculo contra llamadas accidentales, no seguridad: el modelo que llama puede establecer confirm: true por sí mismo. El nivel 3 es un límite real, porque solo quien configura el entorno del servidor puede desbloquearlo. Si apuntas un agente autónomo a una bóveda que te importa, ejecuta con OBSIDIAN_MCP_READONLY=1, que rechaza todo comando mutante antes del envío, independientemente del nivel.

Movimientos y renombrados seguros para enlaces

La regla más importante en este proyecto: los archivos nunca se mueven, renombran o eliminan a través del sistema de archivos. Obsidian actualiza cada wikilink en la bóveda cuando realiza la operación. Un simple mv no lo hace.

Antes, con Projects/Roadmap.md enlazado desde tres notas:

Weekly Review.md:   Progress on [[Roadmap]] is on track.
Team Notes.md:      See [[Roadmap#Q3]] for the plan.
Index.md:           - [[Roadmap|2026 roadmap]]

Después de move_note con to: "Archive/2026 Roadmap.md":

Weekly Review.md:   Progress on [[2026 Roadmap]] is on track.
Team Notes.md:      See [[2026 Roadmap#Q3]] for the plan.
Index.md:           - [[2026 Roadmap|2026 roadmap]]

Los tres enlaces actualizados, incluyendo el ancla de encabezado y el alias, porque Obsidian realizó el movimiento. Un movimiento del sistema de archivos habría dejado tres enlaces rotos y ningún error.

¿Por qué híbrido? La justificación del rendimiento

Cada invocación de la CLI es un viaje de ida y vuelta IPC completo a través de la aplicación Obsidian en ejecución. Eso es correcto pero lento: leer 2000 notas a través de obsidian read son 2000 viajes de ida y vuelta, minutos de tiempo real. Leerlas del disco es un recorrido de directorio, mucho menos de un segundo en cualquier SSD.

Por lo tanto, las lecturas masivas (búsquedas, listados, escaneos de etiquetas y propiedades, exportaciones, resúmenes) van al sistema de archivos, y la CLI se reserva para lo que solo Obsidian puede responder (enlaces, alias, Bases, plantillas, estado de la aplicación) y para cada escritura. Para comparar en tu propia bóveda, mide el tiempo de search_notes contra el paso directo obsidian_cli con ["search", "query=..."].

Solución de problemas

"Obsidian no se está ejecutando." El fallo más común. La CLI necesita la aplicación abierta y completamente cargada. Inicia Obsidian y vuelve a intentarlo.

"No se pudo encontrar el binario de la CLI de Obsidian." Habilita la CLI en Obsidian en Configuración, General, Interfaz de línea de comandos, o apunta OBSIDIAN_BIN al binario.

Tiempos de espera en el primer comando. Un inicio en frío de Obsidian puede exceder el valor predeterminado de 20s. Aumenta OBSIDIAN_MCP_TIMEOUT.

Las notas se leen como faltantes o el servidor recurre mucho a la CLI. Si tu bóveda está en iCloud con Optimizar almacenamiento de Mac activado, los archivos desalojados existen solo como stubs .name.icloud. El servidor los detecta y los lee a través de Obsidian, que los vuelve a descargar, en lugar de informar notas vacías. Los escaneos masivos omiten los archivos desalojados y lo indican en su salida.

Las escrituras llegan a la bóveda incorrecta. Tienes múltiples bóvedas y no has establecido OBSIDIAN_VAULT. El servidor advierte sobre esto en stderr al inicio. Fija una.

Las herramientas no aparecen en el cliente. Revisa los registros MCP del cliente y verifica el problema de la ruta absoluta de node mencionado anteriormente.

Mantenerse actualizado

git pull && npm install && npm run build

El servidor verifica actualizaciones al inicio, como máximo una vez cada 24 horas, almacenando en caché el resultado en ~/.config/obsidian-cli-mcp/update-check.json. Falla silenciosamente sin conexión e imprime una sola línea en stderr cuando existe una versión más reciente.

Herramientas (39 en total)

Herramientas de lectura (18)

Herramientas de escritura (16)

Todas las escrituras pasan por la CLI. Cada una requiere un objetivo file o path explícito, ninguna puede recaer en el archivo activo actual.

run_obsidian_command es la puerta más amplia del servidor: alcanza todas las acciones de la paleta de comandos, incluyendo las registradas por plugins comunitarios. Está expuesta deliberadamente y protegida en el nivel 2.

Herramientas de flujo de trabajo (4)

Vía de escape (1)

Recursos MCP

El soporte del cliente para recursos varía: Claude Desktop actualmente no los muestra.

Prompts MCP

Arquitectura

src/
├── index.ts              MCP server entry, stdio transport
├── config.ts             Environment configuration
├── adapters/
│   ├── cli.ts            execFile wrapper, vault injection, error contract
│   └── filesystem.ts     Read-only vault access, iCloud stub detection
├── tools/
│   ├── common.ts         Shared note loading with CLI fallback
│   ├── read.ts           18 read tools
│   ├── write.ts          16 write tools
│   ├── workflow.ts       4 composite tools
│   └── passthrough.ts    obsidian_cli escape hatch
├── resources/
│   └── vault.ts          MCP resources
├── prompts/
│   └── workflows.ts      MCP prompts
└── utils/
    ├── guardrails.ts     Tier policy, readonly allowlist
    ├── markdown.ts       Frontmatter, headings, tags, word counts
    ├── output.ts         Truncation at 60,000 characters
    └── update-check.ts   Daily update check

Las pruebas se ejecutan contra un binario simulado que escanea su argv completo y puede configurarse para fallar, colgarse o emitir una salida sobredimensionada, de modo que todo el conjunto de pruebas pase sin tener instalado Obsidian:

npm test

Soporte

Incidencias y solicitudes de funciones: Issues en GitHub.

Más del autor

• things-for-mac-mcp, el servidor MCP hermano para Things 3

Licencia

MIT