obsidian-mcp

Servidor MCP que envuelve la CLI oficial de Obsidian para que un agente LLM pueda controlar una instancia de Obsidian en ejecución: leer/escribir notas, buscar, gestionar metadatos, navegar por enlaces, ejecutar plugins y más.

Este servidor es un envoltorio ligero y completo. Cada herramienta se asigna 1:1 a un comando de la CLI de obsidian.

Requisitos previos

1. Obsidian debe estar ejecutándose. La CLI se comunica con la aplicación activa a través de IPC; no lee el almacén (vault) directamente del disco.

2. Registrar el binario de la CLI. En Obsidian: Ajustes → General → Interfaz de línea de comandos → Registrar CLI. Obsidian añadirá obsidian a tu PATH.

3. Verificar: obsidian version imprime la versión de la CLI.

Instalación

Dos caminos dependiendo de si quieres compilarlo tú mismo o usar una versión prepublicada desde npm.

Opción A — Clonar y compilar (funciona hoy)

Clona el repositorio y compila localmente, luego apunta Claude Code al archivo compilado:

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

Regístralo con Claude Code (un comando):

# Add (user scope — available across all projects)
claude mcp add -s user obsidian -- node /absolute/path/to/obsidian-mcp/dist/index.js

# Remove
claude mcp remove obsidian

# List configured servers
claude mcp list

-s user lo registra para toda tu cuenta de usuario. Usa -s project para confirmarlo en el archivo .mcp.json del repositorio, o -s local solo para el proyecto actual (por defecto).

O escríbelo manualmente en .mcp.json:

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

Opción B — Instalar desde npm (sin compilación)

Requisito previo: el paquete ya debe estar publicado en npm. El mantenedor publica una vez mediante npm publish; todos los usuarios posteriores lo obtienen automáticamente mediante npx. Si has hecho un fork de este repositorio y quieres este flujo bajo tu propio ámbito, cambia name en package.json a @<tu-nombre-de-usuario-npm>/obsidian-mcp, luego ejecuta npm publish.

Una vez publicado, no se necesita clonar ni compilar:

claude mcp add -s user obsidian -- npx -y @yuchichang/obsidian-mcp

O en .mcp.json / claude_desktop_config.json de Claude Desktop:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@yuchichang/obsidian-mcp"]
    }
  }
}

Sobrescribir la ruta de la CLI

Si obsidian no está en el PATH, establece la variable de entorno OBSIDIAN_CLI. Funciona con cualquier ruta de instalación:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_CLI": "C:/Users/you/AppData/Local/Obsidian/obsidian.cmd"
      }
    }
  }
}

Herramientas

Almacén (Vault) y archivos

Propiedades de Frontmatter

Búsqueda

Etiquetas y enlaces

Notas diarias

Plugins

Desarrollador / avanzado

Meta

Convenciones

• Apuntar a una nota — las herramientas que apuntan a archivos aceptan:

  • file — nombre de nota estilo wikilink (ej. "Mi Nota"), o

  • path — ruta de archivo relativa al almacén (ej. "Carpeta/Mi Nota.md").

• Configuraciones multialmacén — cada herramienta acepta un parámetro opcional vault. Cuando se omite, se utiliza el almacén enfocado más recientemente.

• Formato de salida — las herramientas de lista/búsqueda/metadatos devuelven JSON por defecto para facilitar el análisis automático.

Operaciones sensibles y confirmación del usuario

Las siguientes herramientas están protegidas por un paso de confirmación del usuario:

Cómo funciona la protección:

1. Elicitación MCP (preferido). Si el cliente conectado soporta la capacidad elicitation (Claude Code lo hace), el servidor envía una solicitud elicitation/create y el cliente muestra al usuario un aviso de ¿Proceder? con la acción y el objetivo detallados. Solo accept + confirm: true procede.

2. Parámetro explícito confirm: true. El esquema de entrada de cada herramienta sensible incluye un confirm: boolean opcional. Pasar confirm: true omite el aviso de elicitación; úsalo solo cuando el llamador ya haya obtenido la aprobación del usuario.

3. Reserva de rechazo. Si el cliente no soporta la elicitación y no se proporcionó confirm: true, la herramienta devuelve un resultado isError que nombra la acción e instruye al llamador a reintentar con confirm: true.

Omisión para lotes / automatización

OBSIDIAN_MCP_AUTO_CONFIRM=1

Establece esta variable de entorno (en el bloque env de tu cliente MCP) para omitir cada aviso de confirmación. Úsalo solo en contextos de automatización totalmente confiables.

Contenido largo y límites de argv

La CLI de Obsidian no soporta (todavía) la lectura de valores de parámetros desde stdin o desde archivos; cada valor viaja en la línea de comandos. Eso choca con los límites de la plataforma:

Para mantenerse seguro, el servidor fragmenta automáticamente las escrituras largas:

Las divisiones ocurren en los límites de línea cuando es posible; las líneas individuales demasiado grandes recurren a límites de caracteres seguros para UTF-8. El contenido reensamblado es idéntico byte a byte al original.

Configura el umbral de bytes por llamada (por defecto: 6,000 en Windows, 100,000 en otros lugares):

OBSIDIAN_MCP_MAX_ARG_BYTES=4000

Si un fragmento en medio de una escritura de múltiples fragmentos falla, el servidor devuelve isError con un mensaje claro indicando qué fragmentos llegaron al disco para que el llamador pueda recuperarse.

Desarrollar

npm run dev      # tsc --watch
npm run inspect  # launch MCP Inspector against the built server
node scripts/smoke-test.mjs   # initialize + tools/list smoke test

Cómo funciona

runObsidian() (src/exec.ts) cita los argumentos para el shell, invoca el binario obsidian a través de child_process.exec y analiza stdout. La mayoría de las herramientas de lectura solicitan format=json; los resultados se analizan en structuredContent para los clientes que consumen salida de herramientas estructurada, mientras siguen devolviendo una representación de texto en content.

El registro de herramientas reside en src/tools.ts: añadir un nuevo comando envuelto es una sola entrada allí.

Referencia

• CLI de Obsidian: https://obsidian.md/help/cli

• Especificación MCP: https://modelcontextprotocol.io