obsidian-cli-mcp es un servidor MCP para la CLI oficial de Obsidian. Expone operaciones de búsqueda, notas, tareas, archivos, enlaces y Canvas nativo del vault de Obsidian a un cliente MCP. El servidor no reemplaza 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. HTTP Streamable remoto está disponible como una configuración avanzada y asegurada por separado; no es necesario para uso local.
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, 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 admite obsidian-headless. La aplicación de Obsidian debe permanecer abierta mientras se usa el servidor MCP.
Comprueba primero el lado de Obsidian:
command -v obsidian
obsidian version
obsidian vaultRelated MCP server: Obsidian MCP Server
Inicia el paquete publicado v0.4.1 desde cualquier directorio:
npx --yes --package=@dariuscodes/obsidian-cli-mcp@0.4.1 obsidian-cli-mcpEl comando habla MCP sobre stdio y espera a un cliente MCP. Intencionalmente 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.jsNo se requiere nombre de vault, ruta de vault, token, cuenta de Cloudflare, LaunchAgent ni archivo de configuración para el valor predeterminado local. El servidor usa el vault activo que Obsidian expone a través de la CLI oficial.
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 tu PATH de shell, reemplaza npx con 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 de MCP. La primera secuencia útil es:
Llama a vault_search con una consulta que debería existir en tu vault, por ejemplo { "query": "meeting", "limit": 10 }.
Pasa una ruta devuelta a note_read, por ejemplo { "path": "<ruta devuelta por vault_search>" }.
Vista previa de 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 note_create. Devuelve la acción planificada y el comando CLI exacto sin cambiar el vault. Solo usa dryRun: false después de revisar el plan. dryRun es una vista previa, no un límite de autorización.
Para Canvas, vista previa de 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 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 campos desconocidos, validan referencias de nodos/aristas y no requieren eval arbitrario.
Una configuración vacía o ausente es utilizable para un vault de Obsidian estándar. El .obsidianmcprc.yaml opcional se descubre 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 de eval fijos internos utilizados por algunas operaciones seguras no son una vía de escape de JavaScript proporcionada por el usuario.
Las importaciones desde archivos locales arbitrarios están deshabilitadas hasta que imports.allowedRoots se configure explícitamente. Las URL nunca se obtienen.
Los segmentos de ruta .obsidian, .git, .trash, .Trash, Trash y .DS_Store están bloqueados por defecto. Agrega paths.allow para un área de vault más estrecha y agrega 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; la eliminación permanente requiere la configuración explícita delete.mode: hard.
El autocommit de Git está desactivado por defecto.
Usa una lista de permitidos explícita cuando un cliente MCP solo deba inspeccionar el vault:
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_readEl 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 eliminación, importaciones de archivos, operaciones de ciclo de vida de archivos y 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: []Omite tools.allow para exponer la superficie completa de herramientas integradas, manteniendo las rutas protegidas predeterminadas, la eliminación a la papelera, las importaciones deshabilitadas y obsidian_eval deshabilitado. Si se necesitan importaciones, configura solo un directorio de origen local dedicado:
imports:
allowedRoots:
- /absolute/path/to/approved-imports
maxBytes: 26214400
collision: increment
delete:
mode: trash
eval:
enabled: falseConsulta docs/configuration.md para todos los campos y examples/ para presets de organización de notas.
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 endpoint público.
HTTP Streamable es un modo avanzado opcional para un cliente que no puede usar stdio local. Se vincula solo a loopback y se niega a iniciar 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.
El servidor predeterminado anuncia 43 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.
Lote: vault_batch ejecuta lecturas habilitadas y previsualiza mutaciones habilitadas con args.dryRun: true, control de dependencias, resultados estables en orden de entrada y un batch.maxParallelism acotado (predeterminado 4, máximo 8).
Todas las herramientas de mutación aceptan dryRun. Las anotaciones de herramientas identifican operaciones de solo lectura y destructivas para clientes MCP compatibles.
Obsidian Desktop debe estar en ejecución, su CLI oficial debe estar habilitada y el vault activo debe estar disponible para esa sesión de escritorio. Este servidor no es un sandbox y no admite obsidian-headless.
El contenido del vault 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 un vault solo porque fueron devueltas por una herramienta. La salida de las herramientas también puede contener contenido sensible del vault, así que conecta solo clientes en los que confíes.
Lee SECURITY.md antes de habilitar HTTP remoto, importaciones, eliminaciones permanentes o una lista de permitidos de mutaciones amplia. Reporta problemas de seguridad de forma privada como se describe allí.
El checkout del código fuente usa Bun, mientras que el bin 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 --jsonLa 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:liveGitHub Actions ejecuta solo compuertas sin conexión; no depende de Obsidian Desktop ni de un vault real en un runner alojado.
This server cannot be deployed
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
