obsidian-cli-mcp

obsidian-cli-mcp es un servidor MCP para la CLI oficial de Obsidian. Expone operaciones de búsqueda en la bóveda, notas, tareas, archivos, enlaces y Canvas nativo de Obsidian a un cliente MCP. El servidor no sustituye a Obsidian: la CLI reenvía las solicitudes a la aplicación de escritorio de Obsidian en ejecución.

El transporte predeterminado es stdio local. Streamable HTTP remoto está disponible como configuración avanzada y asegurada por separado; no es necesario para uso local.

Requisitos

• macOS con Obsidian Desktop instalado y en ejecución.

• La CLI oficial de Obsidian habilitada en Obsidian: Configuración → General → Interfaz de línea de comandos, y luego registra obsidian en tu PATH.

• Node.js 18 o superior para ejecutar el paquete publicado. Bun solo se necesita para compilar o desarrollar este checkout del código fuente.

Este proyecto requiere la CLI de escritorio. No es compatible con obsidian-headless. La aplicación de Obsidian debe permanecer abierta mientras se use el servidor MCP.

Comprueba primero el lado de Obsidian:

command -v obsidian
obsidian version
obsidian vault

Inicio rápido con npm

Ejecuta el paquete publicado v0.4.1 desde cualquier directorio:

npx --yes --package=@dariuscodes/obsidian-cli-mcp@0.4.1 obsidian-cli-mcp

El comando usa MCP a través de stdio y espera a un cliente MCP. Intencionadamente no imprime datos de protocolo en la terminal. Los diagnósticos van a stderr.

Para un checkout del código fuente en su lugar:

git clone https://github.com/DariusCorvus/obsidian-cli-mcp.git
cd obsidian-cli-mcp
bun install --frozen-lockfile
bun run build
node dist/main.js

No se requiere nombre de bóveda, ruta de bóveda, token, cuenta de Cloudflare, LaunchAgent ni archivo de configuración para el valor predeterminado local. El servidor usa la bóveda activa que Obsidian expone a través de la CLI oficial.

Conectar un cliente MCP

Para un cliente que acepte una configuración mcpServers, usa el comando npm:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=@dariuscodes/obsidian-cli-mcp@0.4.1",
        "obsidian-cli-mcp"
      ]
    }
  }
}

Si el cliente no hereda el PATH de tu shell, sustituye npx por la ruta absoluta que imprime command -v npx. Para un checkout del código fuente, usa command: "node" y args: ["/absolute/path/to/obsidian-cli-mcp/dist/main.js"].

Reinicia el cliente después de cambiar su configuración MCP. La primera secuencia útil es:

1. Llama a vault_search con una consulta que debería existir en tu bóveda, por ejemplo { "query": "meeting", "limit": 10 }.

2. Pasa una de las rutas devueltas a note_read, por ejemplo { "path": "<path returned by vault_search>" }.

3. Previsualiza una mutación segura de nota antes de aplicarla:

   {
     "name": "MCP smoke note",
     "content": "Created after reviewing the plan.",
     "dryRun": true
   }

   Esta es una llamada a note_create. Devuelve la acción planificada y el comando CLI exacto sin modificar la bóveda. Usa dryRun: false solo después de revisar el plan. dryRun es una vista previa, no un límite de autorización.

4. Para Canvas, previsualiza un archivo Canvas nativo y un nodo de texto:

   {
     "path": "MCP smoke.canvas",
     "nodes": [
       {
         "id": "hello",
         "type": "text",
         "x": 0,
         "y": 0,
         "width": 320,
         "height": 180,
         "text": "Hello from MCP"
       }
     ],
     "dryRun": true
   }

   Esta es una llamada a canvas_create. Revisa el plan y luego llámala con dryRun: false si quieres crear el archivo. Usa canvas_read para inspeccionar el JSON .canvas nativo después. Las herramientas de Canvas conservan los campos desconocidos, validan las referencias de nodos/bordes y no requieren eval arbitrario.

Configuración y valores predeterminados seguros

Una configuración vacía o inexistente es utilizable para una bóveda de Obsidian estándar. El .obsidianmcprc.yaml opcional se detecta desde el directorio de trabajo del servidor. Para clientes con un directorio de trabajo impredecible, establece OBSIDIAN_MCP_CONFIG a una ruta explícita de archivo de configuración.

La política predeterminada es deliberadamente local y acotada:

• El servidor v0.4.0 no expone una herramienta genérica obsidian_eval. eval.enabled es false por defecto; los fragmentos eval internos fijos que usan unas pocas operaciones seguras no son una puerta de escape de JavaScript proporcionada por el usuario.

• Las importaciones desde archivos locales arbitrarios están deshabilitadas hasta que se configure explícitamente imports.allowedRoots. Las URL nunca se obtienen.

• Los segmentos de ruta .obsidian, .git, .trash, .Trash, Trash y .DS_Store están bloqueados por defecto. Añade paths.allow para un área de bóveda más restringida y prefijos paths.deny específicos del proyecto para contenido más sensible.

• Las mutaciones exponen dryRun. file_delete requiere confirm: true y note_delete usa la papelera de Obsidian por defecto; el borrado permanente requiere la configuración explícita delete.mode: hard.

• El autocommit de Git está desactivado por defecto.

Preajuste de solo lectura

Usa una lista de permitidos explícita cuando un cliente MCP solo deba inspeccionar la bóveda:

tools:
  allow:
    - vault_search
    - note_read
    - note_list
    - vault_tags
    - unresolved_links
    - tasks_list
    - note_diff
    - backlinks_get
    - outlinks_get
    - file_read_binary_metadata
    - canvas_read

Preajuste local seguro

El valor predeterminado tiene protecciones locales seguras pero no es de solo lectura. Para una superficie local segura explícita que permita ediciones normales de notas y creación de Canvas, omitiendo el borrado, las importaciones de archivos, las operaciones del ciclo de vida de archivos y la evaluación arbitraria:

tools:
  allow:
    - vault_search
    - note_read
    - note_list
    - vault_tags
    - unresolved_links
    - tasks_list
    - note_diff
    - backlinks_get
    - outlinks_get
    - canvas_read
    - canvas_create
    - canvas_upsert_nodes
    - canvas_upsert_edges
    - canvas_add_node
    - canvas_add_edge
    - canvas_auto_layout
    - canvas_open
    - note_create
    - note_append
    - note_set_frontmatter
    - note_replace_range
    - note_insert_at
    - note_replace
    - note_insert
    - daily_open
    - daily_append
    - task_create
    - task_update
delete:
  mode: trash
eval:
  enabled: false
imports:
  allowedRoots: []

Preajuste local completo de confianza

Omite tools.allow para exponer la superficie completa de herramientas integradas, manteniendo las rutas protegidas predeterminadas, el borrado a la papelera, las importaciones deshabilitadas y obsidian_eval deshabilitado. Si se necesitan importaciones, configura solo un directorio local de origen dedicado:

imports:
  allowedRoots:
    - /absolute/path/to/approved-imports
  maxBytes: 26214400
  collision: increment
delete:
  mode: trash
eval:
  enabled: false

Consulta docs/configuration.md para todos los campos y examples/ para preajustes de organización de notas.

Stdio local frente a HTTP remoto

El stdio local inicia un proceso de servidor directamente desde el cliente MCP. Es la instalación recomendada: no hay socket de escucha, autenticación remota, configuración de Cloudflare ni punto final público.

Streamable HTTP es un modo avanzado opcional para un cliente que no puede usar stdio local. Se vincula solo a loopback y se niega a iniciarse sin validación JWT de Cloudflare Access o un token de capacidad fuerte. Colócalo detrás de un proxy inverso o túnel TLS autenticado; no lo vincules a 0.0.0.0. Consulta docs/remote-cloudflare.md para la configuración avanzada genérica y sus compensaciones de seguridad.

Superficie de herramientas

El servidor predeterminado anuncia 42 herramientas regulares:

• Lectura: vault_search, note_read, note_list, vault_tags, unresolved_links, tasks_list, note_diff, backlinks_get, outlinks_get, file_read_binary_metadata, canvas_read.

• Escritura y flujo de trabajo: note_create, note_append, note_set_frontmatter, daily_open, daily_append, note_replace_range, note_insert_at, note_replace, note_insert, task_create, task_update, note_transition.

• Archivos y adjuntos: file_import, attachment_import, note_attach, attachment_embed, file_move, file_rename, file_delete, note_rename, note_move, folder_create, note_delete.

• Canvas: canvas_create, canvas_upsert_nodes, canvas_upsert_edges, canvas_remove, canvas_open, canvas_add_node, canvas_add_edge, canvas_auto_layout.

Todas las herramientas de mutación aceptan dryRun. Las anotaciones de herramientas identifican operaciones de solo lectura y destructivas para clientes MCP compatibles.

Limitaciones y seguridad

Obsidian Desktop debe estar en ejecución, su CLI oficial debe estar habilitada y la bóveda activa debe estar disponible para esa sesión de escritorio. Este servidor no es un entorno aislado y no es compatible con obsidian-headless.

El contenido de la bóveda son datos no confiables. Las notas, el texto de Canvas, el texto de tareas y los resultados de búsqueda pueden contener instrucciones de inyección de prompts; un cliente MCP debe tratarlos como datos y nunca seguir instrucciones encontradas dentro de una bóveda solo porque fueron devueltas por una herramienta. La salida de las herramientas también puede contener contenido sensible de la bóveda, así que conecta solo clientes en los que confíes.

Lee SECURITY.md antes de habilitar HTTP remoto, importaciones, borrados permanentes o una lista de mutaciones amplia. Informa de los problemas de seguridad de forma privada como se describe allí.

Desarrollo y CI

El checkout del código fuente usa Bun, mientras que el binario publicado se ejecuta en Node:

bun install
bun run typecheck
bun test
bun run build:schema
bun run build
bun run smoke:stdio
git diff --check
npm pack --dry-run --json

La prueba de humo stdio sin conexión verifica el punto de entrada del paquete compilado, la inicialización de MCP, tools/list, la superficie de herramientas esperada y la ausencia de obsidian_eval. La prueba de humo real de Obsidian es separada y requiere una sesión de usuario con Obsidian en ejecución:

OBSIDIAN_CLI_BINARY=obsidian \
  OBSIDIAN_MCP_CONFIG=/absolute/path/to/your/config.yaml \
  OBSIDIAN_MCP_VAULT="your-vault-name" \
  bun run smoke:live

GitHub Actions ejecuta solo comprobaciones sin conexión; no depende de Obsidian Desktop ni de una bóveda real en un runner alojado.

Licencia

MIT