obsidian-mcp (Python)

Un servidor MCP (Model Context Protocol) en Python que proporciona a un cliente LLM (p. ej. Claude Desktop) acceso de lectura/escritura a bóvedas locales de Obsidian, mediante acceso directo al sistema de archivos: sin plugin de Obsidian Local REST API, sin HTTP, sin token de autenticación.

Esta es una adaptación a Python de obsidian-mcp (TypeScript), funcionalmente equivalente con algunos arreglos y simplificaciones deliberados; consulte Plans/review-the-typescript-obsidian-mcp-parsed-shamir.md e ISA.md para conocer la justificación completa.

Advertencia: Este servidor tiene acceso de lectura/escritura a su bóveda. Haga una copia de seguridad de sus notas (p. ej. mediante git) antes de usarlo.

Requisitos

• Python 3.11+

• uv

• Una bóveda de Obsidian (un directorio que Obsidian haya abierto al menos una vez, es decir, que contenga un .obsidian/app.json)

• macOS o Linux (Windows no es compatible; consulte ISA «Out of Scope»)

Related MCP server: Obsidian MCP Server

Instalación y ejecución

uv sync
uv run obsidian-mcp /path/to/your/vault [/path/to/another/vault ...]

Los nombres de las bóvedas se derivan automáticamente del nombre base de cada directorio (en minúsculas, los caracteres no alfanuméricos se convierten en guiones y los duplicados reciben un sufijo numérico). Hasta 10 bóvedas; las rutas de las bóvedas no deben estar anidadas unas dentro de otras.

Configuración de Claude Desktop

Edite claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/py-obsidian-mcp", "obsidian-mcp", "/path/to/your/vault"]
    }
  }
}

Herramientas

read-note, create-note, edit-note (append/prepend/replace/delete), delete-note (eliminación suave en .trash/ de forma predeterminada), move-note, create-directory, search-vault (búsqueda de contenido/nombre de archivo/etiqueta, con un max_results opcional), add-tags, remove-tags, rename-tag (en toda la bóveda, preservando la jerarquía), list-available-vaults.

También expone un esquema de recurso obsidian-vault:// (listado/información de bóvedas) y un prompt list-vaults.

Desarrollo

uv sync --all-extras
uv run pytest -q
uv run ruff check src tests

Notas de seguridad

• Cada herramienta valida que las rutas de destino permanezcan dentro de la bóveda (src/obsidian_mcp/utils/path_safety.py), incluidos los controles de contención que tienen en cuenta los enlaces simbólicos.

• El original en TypeScript tenía un error confirmado por el que este control de contención era efectivamente una operación nula (una función de validación asíncrona se llamaba sin await). Las funciones de seguridad de rutas de esta adaptación son todas síncronas, lo que impide estructuralmente esa clase de error.