obsidian-mcp-server

Un servidor MCP (Model Context Protocol) para un vault de estudio de Obsidian. Da a Claude acceso a la búsqueda de notas, el contenido de las notas, la creación de flashcards en el formato de Decks y la planificación de estudio del plugin Lerntracker.

Python, MCP SDK 2.x, transporte stdio.

Propósito

Hasta ahora, la lógica vivía en dos plugins de Obsidian:

• Decks (plugin de terceros) renderiza flashcards, pero no las crea — las tarjetas se escribían a mano.

• Lerntracker (plugin propio) gestiona el progreso de estudio y el plan de estudio, pero no distribuye el material automáticamente en días.

Este servidor cierra ambas brechas: Claude puede crear tarjetas directamente en el formato de archivo existente y calcular un plan de estudio que se escribe de vuelta en la data.json del Lerntracker.

Related MCP server: Nexus MCP for Obsidian

Instalación

cd ~/Projects/obsidian-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuración

Ambas rutas provienen de variables de entorno — nada está hardcodeado.

El valor predeterminado para la ruta del vault se ajusta a un Obsidian sincronizado con iCloud; para otra configuración basta con establecer OBSIDIAN_VAULT_PATH.

La ruta del Lerntracker se puede configurar por separado, porque los vaults de Obsidian pueden estar anidados: si en una subcarpeta hay otro vault, este tiene su propia data.json. El valor predeterminado apunta a la del vault principal.

Herramientas

Todos los esquemas son generados por el SDK a partir de type hints y docstrings — en el código no hay ningún esquema JSON escrito a mano.

Formato de flashcard

create_flashcard escribe exactamente el formato que usan las tarjetas existentes en el vault (párrafo de cabecera), ampliado con un wikilink a la fuente:

---
tags: [decks]
---

## Was ist ein Signal?

Eine zeitabhängige, messbare physikalische Größe.

Quelle: [[01_Physikalische_Schicht]]

El archivo de destino se deriva de la carpeta del curso de la nota fuente; deck sobrescribe el nombre del archivo. Si el archivo no existe, se crea con tags: [decks]. Una tarjeta con el mismo anverso se omite en lugar de crearse duplicada.

El estado de aprendizaje de Decks reside en una base de datos SQLite, no en los archivos Markdown. El servidor no la toca — el historial FSRS permanece intacto.

Por qué generate_summary no resume por sí mismo

El servidor no tiene un modelo de lenguaje. Devuelve la nota de forma estructurada (esquema, cifras clave, texto completo); el resumen lo escribe el modelo en el lado del cliente — es decir, Claude Desktop. Se guarda posteriormente con save_summary. Es la distribución de roles habitual en MCP: el servidor proporciona contexto y ejecuta acciones, el modelo formula.

Si el servidor debiera resumir por sí mismo, tendría que llamar a la API de Anthropic y necesitaría su propia clave de API.

Lógica del plan de estudio

generate_study_plan distribuye cada subtema pendiente en días concretos:

1. Los cursos se ordenan por fecha de examen — el examen más temprano primero.

2. Fin de estudio = examDate − bufferDays; los días de margen quedan libres para repaso.

3. Los días de estudio provienen de settings.weeklyHours (0 = domingo … 6 = sábado). Los días con 0 horas y todas las blockedDates se omiten.

4. Cada subtema cuesta hours_per_subtopic (por defecto 1,5 h) y se coloca en el día más temprano con capacidad restante. Si no cabe en un día, se divide en varios días — el plugin admite múltiples dates.

5. Los subtemas ya marcados y aquellos con dates existentes permanecen intactos.

6. Lo que ya no cabe antes del fin de estudio se informa como advertencia en lugar de descartarse silenciosamente.

Antes de cada escritura se crea una copia de seguridad junto al archivo (data.backup-<timestamp>.json); la escritura es atómica mediante un archivo temporal. dry_run=True solo muestra el plan.

Después de escribir en Obsidian, pulsar Cmd+R para que el plugin se recargue.

Recursos

La plantilla usa deliberadamente {+path} (Reserved Expansion) en lugar de {path}. Las variables de plantilla normales no coinciden con barras — con {path} cada nota en una subcarpeta no se encontraría silenciosamente, y en el vault prácticamente todas las notas están en una carpeta de curso.

Probar localmente con el MCP Inspector

El Inspector se inicia mediante la CLI del SDK y abre una interfaz web en la que se pueden invocar herramientas y recursos individualmente. Necesita npx (Node.js) y uv.

source .venv/bin/activate && mcp dev main.py

El comando devuelve una URL como http://localhost:6274 (con un token de sesión adjunto). Abrir en el navegador, hacer clic en Connect a la izquierda, luego:

• Pestaña Tools → List Tools → elegir una herramienta, introducir argumentos, Run Tool

• Pestaña Resources → List Resources → hacer clic en vault://structure

• Para el recurso con plantilla, introducir el URI directamente, siguiendo el patrón note://<Kursordner>/Flashcards/<Datei>.md

Con un vault diferente:

OBSIDIAN_VAULT_PATH="$HOME/Pfad/zu/deinem/Vault" mcp dev main.py

Para probar las herramientas de escritura, merece la pena un vault desechable:

OBSIDIAN_VAULT_PATH=/tmp/testvault mcp dev main.py

Conexión con Claude Desktop

Archivo de configuración: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "/Users/DEIN_NAME/Projects/obsidian-mcp-server/.venv/bin/python",
      "args": ["/Users/DEIN_NAME/Projects/obsidian-mcp-server/main.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/DEIN_NAME/Pfad/zu/deinem/Vault"
      }
    }
  }
}

Importante: usar rutas absolutas — ~ y $HOME no se expanden aquí. Como command, indicar el Python del venv: Claude Desktop inicia el servidor sin entorno activado, un simple "python3" no encontraría el paquete mcp.

Si el archivo ya existe, solo insertar la entrada "obsidian-vault" en el objeto mcpServers existente. Después cerrar Claude Desktop por completo y reiniciarlo; el servidor aparecerá entonces en el menú de herramientas del campo de entrada.

Seguridad

Cada ruta de una llamada de herramienta o recurso se verifica contra el vault: las rutas absolutas y el traversal .. se rechazan, y el destino resuelto debe estar dentro de OBSIDIAN_VAULT_PATH. .obsidian, .git, .trash, .claude y node_modules están excluidos de la búsqueda y el listado de estructura — los bundles de plugins inundarían los resultados de otro modo.

save_summary no sobrescribe un archivo existente, create_flashcard no crea una tarjeta duplicada, y generate_study_plan respalda data.json antes de escribir.

Probado

Contra mcp 2.0.0 en Python 3.14: esquemas de herramientas, plantillas de recursos, handshake stdio con una ClientSession real, guards de ruta, así como las herramientas de escritura contra un vault desechable (incluyendo división en varios días, días bloqueados, días de la semana con cero horas y el caso de desbordamiento).

Licencia

MIT — ver LICENSE.