Obsidian MCP

Lee, escribe, busca y navega tus notas de Obsidian usando lenguaje natural.

Documentación

obsidian-mcp

Un servidor MCP (Model Context Protocol) que da a los asistentes de IA acceso directo a tu bóveda de Obsidian. Lee, escribe, busca y navega por notas usando lenguaje natural — con cualquier cliente compatible con MCP.

Requisitos previos

Node.js 18+ — nodejs.org
Una bóveda de Obsidian (una carpeta de archivos .md — no se requiere la aplicación Obsidian en tiempo de ejecución)

Instalación

No ejecutas el servidor manualmente — tu cliente de IA (Claude Desktop, Cursor, etc.) lo lanza automáticamente al iniciarse. Todo lo que necesitas hacer es compilar el proyecto una vez y apuntar la configuración de tu cliente al archivo de salida.

1. Clona y compila:

git clone <repo-url> obsidian-mcp
cd obsidian-mcp
npm install
npm run build

Esto produce dist/index.js — el archivo al que hará referencia cada configuración de cliente.

2. Encuentra la ruta de tu bóveda. Esta es la carpeta que Obsidian abre como tu bóveda, por ejemplo /Users/yourname/Documents/MyVault.

3. Sigue la configuración para tu cliente a continuación. Cada configuración le indica al cliente:

dónde está el archivo compilado (dist/index.js)
qué bóveda usar (OBSIDIAN_VAULT_PATH)

Configuración del cliente

Todos los clientes usan transporte stdio — el servidor se ejecuta como un subproceso local en tu máquina. No se requiere hosting.

Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Cierra y relanza Claude Desktop. Un icono de martillo (🔨) en la entrada de chat confirma que el servidor está conectado.

Claude Code (CLI)

Registra el servidor con el comando claude mcp add:

claude mcp add obsidian \
  node /absolute/path/to/obsidian-mcp/dist/index.js \
  -e OBSIDIAN_VAULT_PATH=/path/to/your/vault

Verifica que esté registrado:

claude mcp list

Las herramientas ahora están disponibles en cualquier sesión de Claude Code.

Cursor

Abre Configuración → Configuración de Cursor → MCP (o edita ~/.cursor/mcp.json):

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

Reinicia Cursor. Las herramientas aparecen automáticamente en el chat de IA y Composer de Cursor.

VS Code

VS Code admite servidores MCP a través de varias extensiones. La configuración va en .vscode/mcp.json (a nivel de proyecto) o en tu settings.json de usuario (global).

GitHub Copilot (VS Code 1.99+)

Crea .vscode/mcp.json en tu proyecto, o añádelo a Configuración de usuario (JSON):

{
  "servers": {
    "obsidian": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

En GitHub Copilot Chat, cambia al modo Agente (@workspace) — las herramientas de obsidian estarán disponibles automáticamente.

Cline

Abre el panel de configuración de Cline → Servidores MCP → Añadir servidor → pega:

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

Continue

Edita ~/.continue/config.json:

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

Zed

Edita ~/.config/zed/settings.json:

{
  "context_servers": {
    "obsidian": {
      "command": {
        "path": "node",
        "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
        "env": {
          "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
        }
      }
    }
  }
}

Las herramientas están disponibles en el panel del Asistente de IA de Zed.

Ollama (vía mcphost)

Ollama no admite MCP de forma nativa. Usa mcphost como puente: envuelve cualquier servidor MCP y lo conecta a un modelo local de Ollama.

1. Instala mcphost:

go install github.com/mark3labs/mcphost@latest

2. Crea un archivo de configuración (~/.mcphost/config.json):

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

3. Inicia una sesión de chat con cualquier modelo de Ollama:

mcphost --model ollama:qwen2.5:14b

La calidad del uso de herramientas depende en gran medida del modelo. Recomendados: qwen2.5:14b, llama3.1:8b, mistral-nemo. Los modelos deben admitir llamadas a funciones/herramientas para usar las herramientas MCP de manera fiable.

Herramientas disponibles

Herramienta	Descripción
`obsidian_list_notes`	Lista las notas de la bóveda, opcionalmente filtradas a una carpeta. Paginado.
`obsidian_read_note`	Lee el contenido completo de una nota mediante la ruta relativa a la bóveda.
`obsidian_create_note`	Crea una nueva nota con frontmatter YAML opcional.
`obsidian_update_note`	Sobrescribe el contenido y el frontmatter de una nota existente.
`obsidian_append_to_note`	Añade contenido a una nota (la crea si no existe).
`obsidian_delete_note`	Elimina permanentemente una nota.
`obsidian_move_note`	Mueve o renombra una nota a una nueva ruta.
`obsidian_get_note_metadata`	Lee solo el frontmatter y las etiquetas, sin cargar el cuerpo.
`obsidian_search_notes`	Búsqueda de texto completo en todas las notas (sin distinción de mayúsculas).
`obsidian_search_by_tag`	Encuentra todas las notas con un `#tag` específico.
`obsidian_get_backlinks`	Encuentra todas las notas que `[[link]]` a una nota dada.
`obsidian_list_folders`	Lista las carpetas de la bóveda con el número de notas.
`obsidian_create_folder`	Crea una nueva carpeta (las carpetas padre se crean automáticamente).

Todas las herramientas aceptan un parámetro response_format: "markdown" (predeterminado, legible para humanos) o "json" (estructurado, para uso programático).

Ejemplos de instrucciones

"Summarise everything in my projects folder"
"Create a note called 'Meeting Notes 2025-04-11' with today's agenda"
"Find all notes tagged #todo and list what's incomplete"
"What notes link back to my 'Home' note?"
"Search for anything mentioning the Q2 launch"
"Append '- [ ] Follow up with design team' to my Daily Note"

Seguridad

Protección contra recorrido de rutas — todas las rutas se validan para permanecer dentro de OBSIDIAN_VAULT_PATH
Protección de enlaces simbólicos — los enlaces simbólicos dentro de la bóveda que apunten fuera de ella están bloqueados
Límite de tamaño de archivo — las notas mayores de 5 MB se rechazan para evitar agotar la memoria
Límite de tamaño de respuesta — las respuestas se truncan a 25,000 caracteres con un aviso claro
Sin acceso a la red — el servidor solo lee y escribe archivos locales; no hay solicitudes salientes

Extensión

El código base es modular por diseño. Para añadir un nuevo conjunto de herramientas:

Crea src/tools/my-feature.ts y exporta una función registerMyFeatureTools(server, vault)
Añádela a src/tools/index.ts:

import { registerMyFeatureTools } from './my-feature.js';

export function registerAllTools(server: McpServer, vault: VaultService): void {
  registerNoteTools(server, vault);
  registerSearchTools(server, vault);
  registerFolderTools(server, vault);
  registerMyFeatureTools(server, vault);  // ← add this
}

Ejecuta npm run build

Para añadir capacidades a la bóveda (por ejemplo, leer archivos canvas, expansión de plantillas), extiende VaultService en src/services/vault.ts y llama a los nuevos métodos desde tus manejadores de herramientas.