obsidian-mcp-server

[!NOTE] Este repositorio es la edición personalizada huaqing0, basada en cyanheads/obsidian-mcp-server v3.5.0 bajo la licencia Apache-2.0. Conserva el servidor original y añade el espacio de trabajo local, la estructura de bóveda y la automatización nativa de Excalidraw utilizadas en esta edición. Los enlaces de instalación de npm y MCPB siguientes siguen apuntando a la distribución original; esta edición personalizada está actualmente solo en formato fuente.

Herramientas

Treinta y una herramientas cubren el contenido de notas, metadatos, backlinks, automatización nativa de Excalidraw y gestión completa de la estructura de la bóveda, además de una vía de escape protegida para los comandos de la paleta de comandos de Obsidian.

obsidian_get_note

Lee una nota en una de cuatro proyecciones, dirigida por ruta de vault, el archivo activo o una nota periódica (daily, weekly, monthly, quarterly, yearly).

• format: "content" — cuerpo markdown bruto

• format: "full" — contenido, frontmatter, etiquetas y metadatos de archivo; pasa includeLinks: true para incluir referencias salientes escritas más enlaces salientes resueltos por Obsidian y backlinks (solo internos al vault — las URLs externas se filtran)

• format: "document-map" — catálogo de encabezados, referencias de bloque y campos de frontmatter

• format: "section" — valor de sección única de encabezado/bloque/frontmatter (requiere section); las secciones de encabezado incluyen el subárbol completo bajo ese encabezado

Combina la proyección de mapa documental con obsidian_patch_note para descubrir objetivos de edición antes de parchear.

obsidian_search_notes

Hasta tres modos de búsqueda seleccionados por mode:

• text — coincidencia de subcadena con ventanas de contexto circundantes. contextLength controla los caracteres de contexto por lado de cada coincidencia (predeterminado 100; auméntalo para más contexto por acierto). Filtro opcional pathPrefix (solo modo texto — pasar pathPrefix en cualquier otro modo se rechaza con path_prefix_invalid_mode).

• jsonlogic — árbol JSONLogic evaluado contra path, content, frontmatter.<key>, tags y stat.{ctime,mtime,size}; operadores personalizados glob y regexp, ambos toman [PATTERN, VALUE] — patrón primero, luego la referencia de campo: {"glob": ["Projects/*.md", {"var": "path"}]}. El orden inverso compila el propio campo de la nota como patrón: glob entonces no coincide con nada, y regexp falla directamente en lo que sea que el campo analice. Así es también como se expresan los backlinks, ya que no hay una herramienta dedicada ni un endpoint upstream para ellos: {"regexp": ["\\[\\[Target Note(\\||#|\\]\\])", {"var": "content"}]} devuelve cada nota cuyo cuerpo enlaza por wikilink a Target Note.

• omnisearch — búsqueda clasificada por BM25 mediante el plugin comunitario Omnisearch. Admite frases entre comillas, -exclusion, filtros path: / ext:, tolerancia a errores tipográficos, cobertura PDF + OCR (a través de Text Extractor) y coincidencias de imágenes por concepto visual cuando el indexado de AI Image Analyzer está habilitado. Solo está presente en la enumeración de modos cuando el servidor HTTP del plugin es accesible al inicio; el upstream limita los resultados a 50 — estrecha la consulta para mostrar más (la respuesta lleva truncated: true cuando es probable que se haya alcanzado el límite).

Los resultados se paginan mediante cursores opacos según la especificación MCP 2025-11-25: omita cursor para la primera página y luego pase nextCursor de la respuesta anterior. Cada resultado incluye totalCount (post-política de rutas, pre-paginación); nextCursor se omite en la última página. Los resultados en modo texto se recortan además por archivo según maxMatchesPerHit (10 por defecto) para que una sola nota con muchas coincidencias no reviente el presupuesto de la respuesta — los resultados recortados llevan truncated: true y totalMatches.

obsidian_write_note

Crea o reemplaza quirúrgicamente, con un valor predeterminado protector contra sobrescrituras accidentales de archivos completos.

• Sin section — PUT de archivo completo. Se niega a sobrescribir un archivo existente a menos que se establezca overwrite: true. El error file_exists (Conflict) sugiere obsidian_patch_note / obsidian_append_to_note / obsidian_replace_in_note para ediciones in situ.

• Con section — PATCH-con-reemplazo contra el encabezado/bloque/campo de frontmatter nombrado, dejando el resto del archivo intacto. El indicador overwrite se ignora en modo sección.

La salida informa created: true cuando la llamada trajo un archivo nuevo a la existencia; false cuando reemplazó uno existente o apuntó a una sección. Cada herramienta mutadora también devuelve previousSizeInBytes y currentSizeInBytes para que un agente pueda detectar sobrescrituras accidentales, comportamiento inesperado aguas arriba o una ruta con error tipográfico que aterrizó en el archivo equivocado.

obsidian_append_to_note

Una primitiva combinada de upsert + append-de-sección que refleja el comportamiento de la API REST Local aguas arriba:

• Sin section — POST a /vault/{path}. Añade cuando el archivo existe, crea el archivo con su contenido como cuerpo completo cuando no existe. El created: true de la salida marca la segunda rama para que el agente pueda notar cuando una ruta con error tipográfico o una nota diaria aún no creada se convirtió silenciosamente en un archivo nuevo.

• Con section — PATCH-con-append contra el encabezado, la referencia de bloque o el campo de frontmatter nombrado. El archivo debe existir (la verificación previa de PATCH lanza note_missing en caso contrario). Pase createTargetIfMissing: true para hacer que la sección misma cobre existencia dentro de un archivo existente. Los objetivos de referencia de bloque se concatenan adyacentes a la línea del bloque sin separador — incluya un salto de línea inicial en content si desea uno.

previousSizeInBytes es 0 en la rama de creación del upsert y el tamaño real del archivo en caso contrario; currentSizeInBytes es el tamaño posterior a la escritura leído del upstream después de la operación. Compare los deltas contra Buffer.byteLength(content) para detectar inyección automática de saltos de línea o escritores concurrentes.

obsidian_patch_note

Ediciones quirúrgicas en un único objetivo del documento.

• operation: "append" añade después de la sección

• operation: "prepend" añade antes de la sección

• operation: "replace" la intercambia

• Objetivos: ruta de encabezado, ID de referencia de bloque o campo de frontmatter

Los objetivos de encabezado aceptan tanto la ruta completa Parent::Child como un nombre de hoja simple. Una hoja simple que coincide exactamente con un encabezado se expande a su ruta completa antes de la escritura, y la respuesta hace eco del localizador sobre el que aterrizó la edición; una hoja que coincide con varios encabezados se rechaza con ambiguous_section, cuyos datos de error enumeran las rutas candidatas. La misma resolución se aplica a obsidian_write_note y obsidian_append_to_note con section.

Use obsidian_get_note con format: "document-map" para descubrir qué objetivos existen antes de parchear.

obsidian_replace_in_note

Buscar-y-reemplazar para ediciones que no encajan en los objetivos estructurales de obsidian_patch_note. La nota se obtiene, los reemplazos se aplican secuencialmente (cada uno ve la salida anterior) y el resultado se escribe de vuelta en un único PUT.

scope selecciona sobre qué se ejecutan los reemplazos:

• body (predeterminado) — el texto después del bloque de frontmatter YAML. El bloque se vuelve a adjuntar desde los bytes originales, por lo que vuelve byte-idéntico.

• frontmatter — solo el YAML entre los delimitadores ---. Los delimitadores mismos nunca se comparan.

• both — cada reemplazo se ejecuta sobre el frontmatter y luego sobre el cuerpo; perReplacement[] informa bodyCount y frontmatterCount por separado.

Con el frontmatter en el ámbito, el YAML reescrito se vuelve a analizar antes de escribir nada: si ya no se analiza como un mapeo de propiedades, la llamada falla con frontmatter_invalid y la nota conserva sus bytes originales. Esa comprobación detecta YAML que se rompe — un : sin comillas en un escalar, un marcador de lista reescrito como alias, una comilla suelta. No puede detectar una edición que permanece bien formada mientras significa otra cosa, como una colisión de subcadena que renombra una clave o un reemplazo que elimina las comillas de un escalar y cambia su tipo. Prefiera obsidian_manage_frontmatter para ediciones tipadas de una única propiedad.

Opciones por reemplazo:

• useRegex — trata search como una expresión regular ECMAScript. Con useRegex: true, el reemplazo honra las referencias a grupos de captura $1 / $&.

• caseSensitive — cuando es false, compara sin distinguir mayúsculas/minúsculas

• wholeWord — envuelve el patrón en \b…\b; funciona tanto en modo literal como en modo regex

• flexibleWhitespace — sustituye cualquier secuencia de espacios en blanco en search con \s+. Solo modo literal — no tiene efecto cuando useRegex: true (expréselo directamente).

• replaceAll — cuando es false, solo se reemplaza la primera coincidencia. Bajo scope: 'both', esa única sustitución va al frontmatter cuando coincide allí, y al cuerpo en caso contrario.

El modo literal preserva $1 / $& en el reemplazo tal cual — solo useRegex: true expande las referencias a grupos de captura.

obsidian_manage_tags

Añade, elimina o lista etiquetas en una nota. Opera sobre una de dos representaciones, con valor predeterminado en la ubicación canónica de frontmatter de Obsidian:

• location: 'frontmatter' (predeterminado) — solo el array tags: del frontmatter; el cuerpo de la nota se deja intacto

• location: 'inline' — solo la sintaxis #tag en línea en el cuerpo; add añade #tag al final del archivo

• location: 'both' — reconciliación opt-in entre ambas representaciones

add asegura que la etiqueta esté presente en las ubicaciones solicitadas; remove la elimina; list ignora el array tags de entrada. Las ocurrencias de #tag en línea dentro de bloques de código delimitados se dejan intactas intencionalmente.

El modo en línea lee y escribe solo el cuerpo de la nota — un # dentro de un escalar YAML es frontmatter, por lo que ni se lista como etiqueta en línea ni se reescribe mediante una eliminación. Eliminar una etiqueta en línea se lleva exactamente un espacio horizontal adyacente — el que está antes de la etiqueta, o el que está después cuando no hay espacio precedente; cada otro byte sobrevive, incluida la indentación de listas anidadas, los bloques de código indentados con cuatro espacios, los saltos de línea duros de dos espacios finales y el relleno de celdas de tabla.

obsidian_delete_note

Elimina permanentemente una nota. Desactivado por defecto. Establezca OBSIDIAN_ENABLE_DELETE=true para exponerlo en tools/list. La primera llamada responde con una solicitud de confirmación en lugar de una eliminación — el aviso incluye el tamaño en bytes del archivo, de modo que el radio de destrucción sea visible antes de que el usuario confirme — y la herramienta se reintenta con la respuesta. Rechazar o cancelar falla la llamada con cancelled y no emite ningún DELETE; la anotación destructiveHint también hace visible la operación en el flujo de aprobación del host. La salida informa previousSizeInBytes (tamaño en el momento de la eliminación) y currentSizeInBytes: 0.

La confirmación no es opcional y no tiene ruta de respaldo: un cliente que no pueda servir el round-trip de entrada no puede completar una eliminación. Todas las demás herramientas no se ven afectadas.

Herramientas de estructura de la bóveda

obsidian_create_folder crea carpetas anidadas de forma idempotente. obsidian_move_path mueve o renombra archivos o carpetas a través del FileManager nativo de Obsidian, creando los padres de destino faltantes y permitiendo que Obsidian actualice los enlaces internos. obsidian_delete_folder elimina una carpeta recursivamente usando el comportamiento de papelera configurado de Obsidian por defecto, o eliminación permanente cuando se solicita explícitamente; está controlado por OBSIDIAN_ENABLE_DELETE=true junto con la eliminación de notas.

obsidian_execute_command

Despacha un comando de la paleta de comandos de Obsidian por ID (descubrible mediante obsidian_list_commands). El comportamiento depende del comando — algunos comandos abren UI, otros eliminan archivos o cierran la bóveda.

Desactivado por defecto. Cuando OBSIDIAN_ENABLE_COMMANDS no está establecido, tanto obsidian_execute_command como su compañero de descubrimiento obsidian_list_commands se envuelven con disabledTool() — ausentes de tools/list (el LLM no puede invocarlos) pero aún visibles en el manifiesto orientado al operador con una pista para habilitarlos.

Related MCP server: Obsidian Tools MCP Server

Política de rutas (permisos con ámbito de carpeta)

Tres variables de entorno opcionales controlan qué rutas de la bóveda puede apuntar cada herramienta. Sin establecer por defecto = bóveda completa tanto para lecturas como para escrituras — compatible con versiones anteriores.

La coincidencia se basa en prefijos con recursión implícita, sin distinguir mayúsculas/minúsculas, con barras finales normalizadas. projects/ coincide con projects/a.md, projects/sub/b.md, etc.

Las rutas de escritura son implícitamente legibles — no se puede editar sensatamente lo que no se puede ver. Así que una lectura pasa cuando el objetivo coincide con READ_PATHS o WRITE_PATHS.

OBSIDIAN_READ_ONLY=true cortocircuita antes de las comprobaciones de ruta — cada herramienta de escritura y el par de paleta de comandos se envuelven con disabledTool() al inicio (ausentes de tools/list), y cualquier escritura que aún llegue al servicio se deniega en tiempo de ejecución independientemente de WRITE_PATHS.

Las denegaciones se tipan como path_forbidden (código JSON-RPC Forbidden) con el ámbito activo reflejado en data.recovery.hint y data.activeScope, de modo que el LLM pueda autocorregirse sin inspeccionar los registros del servidor. Los resultados de búsqueda de obsidian_search_notes se filtran contra READ_PATHS silenciosamente — mostrar un indicador de "ocultamos N resultados" derrotaría la compuerta.

El listado de etiquetas es de toda la bóveda. obsidian_list_tags y el recurso obsidian://tags agregan nombres de etiquetas en toda la bóveda y no se estrechan por OBSIDIAN_READ_PATHS — no toman ninguna ruta que controlar, por lo que los nombres de etiquetas (nunca los contenidos de notas) de fuera del ámbito de lectura pueden salir a la superficie.

El banner de inicio registra el ámbito activo para que los operadores puedan verificar su configuración al arrancar.

Recursos

Todos los datos de recursos también son accesibles mediante herramientas — obsidian_get_note para obsidian://vault/{+path}, obsidian_list_tags para obsidian://tags. Los recursos existen para clientes que prefieren adjuntar una nota específica o una instantánea de la bóveda a una conversación. El par de etiquetas no es un espejo: obsidian://tags mantiene semántica de instantánea y devuelve la carga útil del upstream completa y sin ordenar, mientras que obsidian_list_tags ordena por recuento y limita.

Características

Construido sobre @cyanheads/mcp-ts-core:

• Definiciones declarativas de herramientas y recursos: un archivo por primitiva, el framework se encarga del registro y la validación

• Manejo de errores unificado: los handlers lanzan, el framework captura, clasifica y formatea. Las herramientas anuncian su superficie de fallo mediante contratos tipados errors[].

• instructions a nivel de servidor en initialize: muestra la orientación específica del despliegue (política de rutas activas, modo de solo lectura, conmutador de paleta de comandos) a clientes compatibles con la especificación, junto con el catálogo estático de herramientas y recursos

• Autenticación conectable en el transporte HTTP: none, jwt, oauth

• Registro estructurado con trazado OpenTelemetry opcional

• Transportes STDIO y HTTP Streamable

El servidor en sí no tiene estado: cada llamada a una herramienta golpea directamente la API REST local. Los backends de almacenamiento del framework, el KV de estado de solicitud y los flujos de progreso no se usan aquí; Obsidian es de una sola bóveda y no hay nada que persistir entre llamadas.

Específico de Obsidian:

• Envuelve el plugin Obsidian Local REST API: cliente tipado, mapeo de errores determinista

• Edición consciente de secciones en encabezados, referencias a bloques y campos de frontmatter mediante operaciones PATCH-con-objetivo

• Reconciliación de etiquetas en ambas representaciones: array tags: de frontmatter y sintaxis en línea #tag (omitiendo bloques de código cercados)

• Búsqueda en hasta tres modos: texto, JSONLogic y (cuando el plugin es accesible) Omnisearch clasificado por BM25: paginada por cursor según la especificación MCP 2025-11-25, con recorte de coincidencias por archivo en modo texto

• Confirmación humana obligatoria en el bucle para eliminaciones destructivas: una ronda input_required de múltiples viajes servida en ambas revisiones del protocolo, sin ruta no confirmada a través de la herramienta

• Gestión nativa de la estructura de la bóveda: crear carpetas, mover/renombrar archivos o carpetas con actualizaciones de enlaces de Obsidian, y eliminar carpetas mediante papelera o eliminación permanente

• Integración nativa de la API de Automatización de Excalidraw: crear/leer/añadir/actualizar/eliminar semánticos, diseño determinista, validación de integridad, exportación de vista previa PNG e incrustación de notas idempotente

• Permisos de lectura/escritura limitados a carpetas mediante OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS y un interruptor global de seguridad OBSIDIAN_READ_ONLY: las denegaciones son path_forbidden tipadas con el ámbito activo reflejado en los datos de error

• Par de paleta de comandos opcional (obsidian_list_commands + obsidian_execute_command): registrado solo cuando OBSIDIAN_ENABLE_COMMANDS=true

• Resolución de rutas tolerante en obsidian_get_note y obsidian_open_in_ui: reintenta silenciosamente rutas con mayúsculas/minúsculas no coincidentes contra el nombre de archivo canónico, lanza Conflict en coincidencias ambiguas de mayúsculas/minúsculas, y enriquece NotFound con sugerencias ¿Querías decir: …? cuando solo existen coincidencias aproximadas. obsidian_delete_note está deliberadamente excluido: una operación destructiva no debería reescribir silenciosamente la ruta objetivo.

Primeros pasos

Añade lo siguiente a tu archivo de configuración del cliente MCP. El plugin Obsidian Local REST API debe estar instalado y habilitado en tu bóveda; consulta Requisitos previos.

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["obsidian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OBSIDIAN_API_KEY": "your-local-rest-api-key"
      }
    }
  }
}

O con npx (sin necesidad de Bun):

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "obsidian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OBSIDIAN_API_KEY": "your-local-rest-api-key"
      }
    }
  }
}

Para Streamable HTTP, establece el transporte y arranca el servidor. Las variables de entorno en línea funcionan para ejecuciones puntuales; para uso repetido, copia los valores en .env (consulta .env.example) y ejecuta bun run start:http.

MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=... bun run start:http
# Server listens at http://127.0.0.1:3010/mcp by default

Requisitos previos

• Bun v1.3.0 o superior (o Node.js v24+).

• El plugin Obsidian Local REST API, v4.0.0 hasta v5.x, instalado y habilitado en tu bóveda. Genera una clave API en Configuración → Plugins de la comunidad → Local REST API y cópiala en OBSIDIAN_API_KEY. El plugin v6.0 elimina el formato de cable markdown-patch 1.x que este servidor fija para escrituras dirigidas a secciones y el mapa de documentos.

• Los objetivos de notas periódicas (target: { "type": "periodic" }) además necesitan el plugin v5.0.1 o anterior: v5.0.2 eliminó las rutas /periodic/ integradas. Todos los demás tipos de objetivo no se ven afectados.

• Un cliente MCP que pueda responder a una solicitud de entrada (elicitation). obsidian_delete_note siempre pide confirmación antes de eliminar, por lo que un cliente sin ese soporte puede leer y escribir notas pero no eliminar ninguna.

• Opcional: el plugin Obsidian Excalidraw instalado y habilitado para usar las once herramientas de dibujo. Las demás herramientas de notas y bóveda no lo requieren.

• Este servidor usa por defecto http://127.0.0.1:27123 por simplicidad. Habilita "Non-encrypted (HTTP) Server" en la configuración del plugin para usarlo. Para usar el puerto HTTPS siempre activo en su lugar, establece OBSIDIAN_BASE_URL=https://127.0.0.1:27124; el certificado autofirmado del plugin se maneja con OBSIDIAN_VERIFY_SSL=false (el valor predeterminado).

Instalación

1. Clona el repositorio:

   git clone https://github.com/cyanheads/obsidian-mcp-server.git

2. Navega al directorio:

   cd obsidian-mcp-server

3. Instala las dependencias:

   bun install

4. Configura el entorno:

   cp .env.example .env
   # edit .env and set OBSIDIAN_API_KEY

Configuración

Consulta .env.example para la lista completa de anulaciones opcionales.

Ejecutar el servidor

Desarrollo local

• Compilar y ejecutar la versión de producción:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Ejecutar comprobaciones y pruebas:

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t obsidian-mcp-server .
docker run --rm -e OBSIDIAN_API_KEY=your-key -p 3010:3010 obsidian-mcp-server

El Dockerfile usa por defecto transporte HTTP, modo de sesión sin estado y registra en /var/log/obsidian-mcp-server. Las dependencias pares de OpenTelemetry se instalan por defecto: compila con --build-arg OTEL_ENABLED=false para omitirlas.

La imagen se vincula a 0.0.0.0 dentro del contenedor (requerido para el mapeo de puertos de Docker). Para cualquier despliegue accesible más allá de tu propia máquina, establece MCP_AUTH_MODE=jwt (con MCP_AUTH_SECRET_KEY) o oauth — de lo contrario, el listener reenvía tu OBSIDIAN_API_KEY a la bóveda en nombre de cada llamador.

Estructura del proyecto

Guía de desarrollo

Consulta CLAUDE.md para las pautas de desarrollo y reglas arquitectónicas. La versión corta:

• Los manejadores lanzan excepciones, el framework las captura — sin try/catch en la lógica de herramientas.

• Usa ctx.log para el registro con ámbito de solicitud, ctx.state para el almacenamiento con ámbito de tenant.

• Registra nuevas herramientas y recursos mediante los barriles en src/mcp-server/*/definitions/index.ts.

• Envuelve las llamadas a APIs externas: valida los datos brutos → normaliza al tipo de dominio → devuelve el esquema de salida; nunca inventes campos faltantes.

Contribuciones

Los errores, las solicitudes de funciones y las lagunas de documentación deben ir en un issue — consulta CONTRIBUTING.md para saber qué hace que uno sea accionable, y CODE_OF_CONDUCT.md para saber cómo trabajamos juntos. Los informes de seguridad se envían a través de SECURITY.md, nunca en un issue público.

Las pull requests son bienvenidas para correcciones pequeñas y autocontenidas. Ejecuta las comprobaciones y pruebas antes de enviarlas:

bun run devcheck
bun run test

Licencia

Apache-2.0 — consulta LICENSE para más detalles.