Obsidian Vault MCP

Servidor HTTP del Model Context Protocol que da a los agentes de IA acceso controlado a una bóveda local de Obsidian.

Construido para entornos de ejecución de agentes (bots de Grok, Claude, OpenClaw, clientes MCP personalizados) que necesitan listar, leer, buscar, crear, actualizar, renombrar y eliminar cuidadosamente notas markdown.

Características

• Endpoint MCP HTTP transmisible (/mcp)

• Autenticación Bearer / clave API

• Modo de bóveda completa (ALLOWLIST=*) o listas de permitidos de carpetas

• Herramientas de lectura: list_notes, list_folder, read_note, search_notes

• Herramientas de escritura: create_note, append_note, update_note, create_folder, rename_path, delete_path

• Bloquea .obsidian, .git, archivos ocultos, .env y material de claves

• Escrituras atómicas + límites de tamaño

• Endpoint de salud para operaciones: /healthz

Related MCP server: obsidian_mcp

Inicio rápido

npm install
export VAULT_ROOT="/absolute/path/to/your/vault"
export BEARER_TOKEN="$(openssl rand -hex 32)"
export ALLOWLIST="*"
export WRITE_ALLOWLIST="*"
export MODE="read-write"
export PORT=8790
export BIND=127.0.0.1
export PUBLIC_BASE="http://127.0.0.1:8790"
npm start

Comprobación de salud:

curl -s http://127.0.0.1:8790/healthz | jq .

Variables de entorno

Encabezados de autenticación aceptados:

• Authorization: Bearer <token>

• X-Api-Key: <token>

• X-Obsidian-Token: <token>

Herramientas MCP

Lectura

• list_notes — listar rutas markdown (prefijo opcional)

• list_folder — listar archivos/directorios (recursive opcional)

• read_note — leer una nota + frontmatter simple

• search_notes — búsqueda de subcadenas sin distinción de mayúsculas/minúsculas

Escritura (cuando MODE=read-write)

• create_note — crear nota markdown (overwrite opcional)

• append_note — añadir a una nota

• update_note — reemplazar nota completa

• create_folder — crear árbol de carpetas

• rename_path — renombrar/mover archivo o carpeta

• delete_path — eliminar archivo o carpeta markdown (recursive para no vacíos)

Seguridad:

• nunca sirve .obsidian, .git, rutas ocultas, .env ni archivos de claves

• escritura limitada a .md / .markdown / .txt

• los anclajes de estructura de nivel superior protegidos no se pueden eliminar por completo

• ningún secreto debe estar en la bóveda ni en la configuración de este servidor confirmada en git

Ejemplo de proxy inverso (nginx)

location ^~ /obsidian-mcp/ {
  proxy_pass http://127.0.0.1:8790/;
  proxy_http_version 1.1;
  proxy_set_header Host $host;
  proxy_set_header Authorization $http_authorization;
  proxy_set_header X-Api-Key $http_x_api_key;
  proxy_buffering off;
}

Expón solo a través de HTTPS y mantén BIND=127.0.0.1 en el proceso Node.

Fragmento de prompt para Grok / agente

You have MCP tools for an Obsidian vault via obsidian-vault-mcp.

Rules:
1. First call list_folder path="" to see top-level structure.
2. Read OBSIDIAN-STRUCTURE.md if present before reorganizing.
3. Prefer append_note for changelogs; do not rewrite history casually.
4. Create notes only as .md under clear topic folders.
5. Never store secrets, tokens, private keys, or .env values.
6. Use search_notes before creating near-duplicate docs.
7. Use rename_path to organize; use delete_path only for clearly obsolete drafts.

Notas de seguridad

• Este servidor es potente. Trata BEARER_TOKEN como una contraseña.

• Prefiere aislamiento de red + autenticación de proxy inverso en producción.

• El modo de escritura de bóveda completa es intencional para agentes internos de confianza; restringe WRITE_ALLOWLIST para bots menos confiables.

• No confirmes .env, tokens ni contenidos reales de la bóveda.

Licencia

MIT