Vault MCP

Un plugin de Obsidian que integra un servidor MCP para interactuar con tus notas usando IA.

GitHub
13
Prueba este MCPPatrocinado

Documentación

Vault MCP

Validate GitHub release Downloads

Este plugin de Obsidian integra un servidor MCP (Model Context Protocol) directamente dentro de Obsidian, proporcionando una forma eficiente para que las aplicaciones interactúen con tu vault.

Solo escritorio

Instalación • Características • Uso • Desarrollo • Guía de Esquemas Notas

obsidian-settings

Características

  • Servidor MCP Integrado: Aloja el servidor MCP dentro de Obsidian como un plugin, simplificando la configuración y mejorando el rendimiento
  • Acceso al Vault vía MCP: Expone tu vault a través de herramientas estandarizadas
  • Soporte de Datos Estructurados: Define esquemas personalizados para la creación y validación de notas estructuradas
  • Operaciones de Archivos:
    • Leer y escribir archivos
    • Búsqueda difusa en todo tu vault
    • Navegar la estructura del vault programáticamente
    • Almacenamiento y acceso a datos estructurados
  • Configurable: Personaliza la configuración del servidor, la disponibilidad de herramientas y la autenticación
  • Autenticación Opcional: Asegura tu servidor con autenticación opcional de token Bearer.

tool-selection

auth-settings

Antecedentes

Vault MCP comenzó como un pequeño componente de un proyecto más grande que necesitaba una alternativa a los métodos tradicionales de RAG. Necesitaba algo que los LLMs pudieran usar para recuperar y actualizar de manera confiable datos estructurados y legibles por humanos, sin depender de bases de datos vectoriales impredecibles o de la ambigüedad de los embeddings.

Los servidores MCP existentes para Obsidian no eran una buena opción. Eran pesados en REST, complejos y no estaban bien adaptados para que los modelos de lenguaje interactuaran de forma natural. Así que este plugin se separó para resolver eso: una interfaz ligera para trabajar con vaults de Obsidian de una manera que sea natural para los LLMs y transparente para los humanos.

Instalación

Plugins de la Comunidad (Recomendado)

  1. Abre Configuración de Obsidian > Plugins de la Comunidad
  2. Busca "Vault MCP"
  3. Haz clic en Instalar y luego en Habilitar
  4. Configura los ajustes según sea necesario

Instalación Manual

  1. Descarga el zip de la última versión
  2. Extrae en <vault>/.obsidian/plugins/
  3. Habilítalo en la configuración de Obsidian

Uso

Configuración Básica

  1. Habilita el plugin en la sección de Plugins de la Comunidad de Obsidian
  2. Abre la configuración del plugin para ajustar:
  • Puerto del Servidor (predeterminado: 3000)
  • Host de Enlace (predeterminado: 127.0.0.1; usa 0.0.0.0 para acceso LAN)
  1. (Opcional) Habilitar Autenticación:
    • Activa Habilitar Autenticación
    • Copia el Token de Autenticación proporcionado
    • Incluye el token en los encabezados HTTP: Authorization: Bearer <your_token>
  2. Haz clic en Reiniciar Servidor para aplicar los cambios

Métodos de Conexión

El plugin actualmente solo admite conexiones Server-Sent Events (SSE) y StreamHTTP. Para aplicaciones que requieren conexiones stdio (como Claude Desktop), necesitarás usar un proxy. Puedes seguir la guía de Cloudflare sobre cómo configurar un proxy local usando mcp-remote.

Aquí hay un ejemplo de claude_desktop_config.json para usar el proxy local mcp-remote.

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:<your_server_port>/sse"]
    }
  }
}

Puedes encontrar la URL correcta en el panel de configuración del plugin, en la sección de endpoints.

Herramientas Disponibles

  • obsidian-mcp-read-file: Obtener el contenido de un archivo
  • obsidian-mcp-diff-edit-file: Editar archivos usando udiff simplificado (ver abajo)
  • obsidian-mcp-search-contents: Búsqueda difusa en el contenido de todos los archivos de tu vault
  • obsidian-mcp-search-filenames: Búsqueda difusa en todos los nombres de archivo de tu vault
  • obsidian-mcp-list-files: Listar archivos y directorios en tu vault con profundidad y límites de resultados personalizables
  • obsidian-mcp-upsert-file: Crear o actualizar archivos
  • obsidian-mcp-rollback-edit: Revertir la última edición de un archivo markdown (revierte el último cambio realizado por las herramientas compatibles)

Herramientas destacadas

obsidian-mcp-diff-edit-file

Esta herramienta edita un solo archivo aplicando un udiff simplificado. Básicamente así es como Cursor y otros editores de código basados en LLM funcionan. Es mejor para modelos más inteligentes, ya que los más pequeños tienden a tener dificultades para crear los diffs con precisión. Para ayudar con este problema, la herramienta devuelve un diff de los cambios reales aplicados al archivo. Esto ayuda al modelo a determinar si los cambios aplicados coincidieron con sus expectativas.

Un ejemplo de este formato de udiff simplificado es el siguiente:

--- example.md
+++ example.md
@@ ... @@
-Old line of text
+New line of text

Este sistema de diff simplificado está inspirado en el formato de diff simplificado de Aider; puedes leer más sobre su trabajo aquí

obsidian-mcp-rollback-edit

Esta herramienta te permite revertir el último cambio realizado en un archivo markdown por las herramientas de escritura de archivos compatibles (obsidian-mcp-diff-edit-file, obsidian-mcp-upsert-file o herramientas de actualización estructurada). Antes de que cualquiera de estas herramientas modifique un archivo, el contenido anterior se guarda en un almacén de reversión. Puedes usar obsidian-mcp-rollback-edit para restaurar el archivo a su estado anterior.

Si hay una reversión disponible, el archivo se restaurará a su contenido anterior y recibirás un mensaje con la marca de tiempo y el motivo del último cambio. Si no, recibirás un mensaje de error.

Ediciones de Datos Estructurados (herramientas dinámicas)

Crea y actualiza contenido estructurado de manera segura en cuanto a tipos usando herramientas.

TL;DR Los LLMs no son confiables al editar directamente formatos estructurados como JSON o YAML. Rompen el formato u olvidan campos. En su lugar, Vault MCP define un esquema para tus datos y lo expone como una herramienta. El modelo luego edita la estructura mediante llamadas a herramientas.

Si quieres escribir un esquema, ve aquí: Escribe Tus Propios Esquemas

Cómo funciona

Los LLMs simplemente son malos trabajando con datos estructurados. Rompen el formato, inyectan su propio formato, olvidan cosas, etc.

Vault MCP adopta un enfoque algo novedoso para manejar datos estructurados: crea una herramienta que el LLM puede llamar para hacer actualizaciones a una estructura de datos.

Cuando el LLM quiere editar los datos estructurados, hace una llamada a la herramienta donde los parámetros de la llamada corresponden a los campos de la estructura de datos.

La mayoría de los modelos "buenos" están entrenados específicamente para hacer llamadas a herramientas, por lo que este es un sistema mucho más estable.

Este mapeo de los datos estructurados a la herramienta se realiza en unos pocos pasos:

  1. Defines un esquema usando JSON Schema (draft-07), escrito en YAML.
  2. Vault MCP lo valida usando un metaschema integrado
  3. El esquema se convierte a un zod
  4. Se crea dinámicamente una herramienta a partir de ese esquema

Esquemas

Cada esquema tiene dos secciones:

  1. metadata Define los detalles de nombres de archivo y almacenamiento
  2. fields Define la estructura de tus datos (se usa para generar la herramienta Zod)

Los esquemas son json schema draft 07, pero escritos en yaml para una mejor usabilidad. Para poder hacer esta generación dinámica de herramientas, el plugin necesita conocer tanto la estructura de los datos estructurados como algunos metadatos sobre nombres de archivo, ubicaciones, etc.

Esquemas de Usuario

Aquí hay un ejemplo de un esquema definido por el usuario para almacenar recetas 
metadata:
  schemaName: "Recipe"
  description: |
    Updates a recipe file given a schema and identifiers. Creates the file if it doesn't exist.
    Uses the Recipe Schema. It merges new non-default data into existing frontmatter.
  identifierField: "recipe_id"
  pathTemplate: "Recipes/${category}/${recipe_id}/Recipe.md"
  pathComponents:
    - category
    - recipe_id

fields:
  recipe_id:
    type: "string"
    description: "Unique identifier for the recipe (e.g., `chocolate_chip_cookies`)."
    optional: false

  category:
    type: "string"
    description: "Recipe category for organizing files (e.g., `Desserts`)."
    optional: false

  title:
    type: "string"
    description: "Name of the recipe (e.g., `Chocolate Chip Cookies`)."
    optional: true

  description:
    type: "string"
    description: "Brief description of the recipe and its highlights."
    optional: true

  servings:
    type: "number"
    description: "Number of servings the recipe yields (must be at least 1)."
    optional: true
    minimum: 1
    maximum: 100
    default: 4

  ingredients:
    type: "array"
    description: "List of ingredients required for the recipe."
    optional: true
    items:
      type: "object"
      properties:
        name:
          type: "string"
          description: "The name of the ingredient (e.g., `all-purpose flour`)."
          optional: false
        quantity:
          type: "string"
          description: "Amount needed (e.g., `2 cups`, `1 tsp`)."
          optional: true

          
---

Esto genera una herramienta MCP que se ve así:

mcp-schema-tool

Cuando la usas para poner datos en Obsidian, el resultado se ve así:

Obsidian-schema-tool

Meta Esquema

Para validar que el esquema definido por el usuario contiene los componentes requeridos, tenemos un meta esquema definido en json schema. Puedes leer el archivo aquí

También ayuda a reducir los tipos a algo que se pueda convertir a zod más claramente.

Puedes usarlo para ver una lista de tipos y modificadores que puedes usar, como valores default, minimum y maximum, etc.

Aquí está la versión yaml del meta esquema 
"$schema": http://json-schema.org/draft-07/schema#
title: MCP Structured Document Schema (JSON Schema Valid)
description: Strict meta-schema for structured tools using zod compatible fields.
type: object
required:
  - metadata
  - fields
properties:
metadata:
  type: object
  required:
    - schemaName
    - description
    - identifierField
    - pathTemplate
    - pathComponents
  properties:
    schemaName:
      type: string
    description:
      type: string
    identifierField:
      type: string
    pathTemplate:
      type: string
    pathComponents:
      type: array
      items:
        type: string
  additionalProperties: false
fields:
  type: object
  patternProperties:
    "^[a-zA-Z_][a-zA-Z0-9_]*$":
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - string
            - number
            - boolean
            - date
            - array
            - object
            - literal
            - unknown
            - any
        description:
          type: string
        default: {}
        minimum:
          type: number
        maximum:
          type: number
        enum:
          type: array
          items: {}
        items:
          type: object
        properties:
          type: object
        required:
          type: array
          items:
            type: string
      additionalProperties: true
  additionalProperties: false
additionalProperties: false

Escribiendo tus propios esquemas

Comienza pensando en dos cosas:

  • Where and how will the file be stored?

Usa metadatos para describir plantillas de nombres de archivo y cómo identificar un archivo (por ejemplo, por ID).

  • What structured data will be in the file?

Usa campos para definir la estructura usando tipos como string, number, array, object, y modificadores como default, minimum, etc.

Una vez definido, tu esquema se convertirá automáticamente en una herramienta que el LLM puede usar para actualizar ese tipo de archivo.

Coloca el esquema que escribas en un directorio "schema" en tu vault de obsidian. El esquema debe definirse en un archivo markdown contenido dentro de un bloque de código con la sintaxis de configuración así:

```yaml schema

Puede haber otro texto en el mismo markdown, como notas o descripciones, pero Vault MCP solo usará el yaml definido en el bloque de código especificado anteriormente.

Coloca la ruta de este directorio en la configuración de herramientas dinámicas en la configuración de Vault MCP y reinicia el plugin para analizar y generar las herramientas dinámicas. Se poblarán en el panel de configuración así:

dynamic settings

La herramienta list-schemas se crea automáticamente cuando las herramientas dinámicas están activas para permitir que los clientes vean los esquemas directamente si es necesario.

Obsidian renderizará la estructura YAML como un frontmatter bien formateado o un bloque incrustado en tu markdown.

Al escribir esquemas, encontré esta herramienta particularmente útil stefanterdell.github.io/json-schema-to-zod-react. Vault MCP la usa internamente para generar el zod, pero este es un método más visual para ayudar en la resolución de problemas.

Desarrollo

Requisitos previos

Se proporciona un nix flake para crear un entorno de desarrollo estandarizado.

Configurar el Entorno de Desarrollo


git clone https://github.com/jlevere/obsidian-mcp-plugin.git
cd obsidian-mcp-plugin

nix develop

# for cool people who use direnv
# echo "use flake" > .envrc && direnv allow

pnpm install

pnpm build:dev

Estructura del Proyecto

  • src/: Código fuente
    • managers/: Gestores de funcionalidad principal
    • structured-tools/: Validación de esquemas y herramientas
    • utils/: Utilidades auxiliares
    • vault/: Código de interacción con el vault
  • tests/: Archivos de prueba

Compilar Producción

pnpm run build

Notas

  • Este plugin solo es compatible con Obsidian de escritorio.
  • Los tokens de autenticación bearer se almacenan en el archivo data.json del plugin. Este token se puede regenerar bajo demanda.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en abrir un issue o un pull request.

Créditos

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.