Obsidian

Un servidor para interactuar con tu bóveda de Obsidian.

GitHub
37
Prueba este MCPPatrocinado

Documentación

Obsidian MCP Server Banner

Servidor de Herramientas MCP de Obsidian

Security Scan (Trivy + Bandit) Bandit Trivy

Este proyecto proporciona un servidor del Protocolo de Contexto de Modelos (MCP) que expone herramientas para interactuar con una bóveda de Obsidian.

Tabla de Contenidos

Características

Permite a los clientes MCP (como asistentes de IA):

  • Leer y escribir notas
  • Gestionar metadatos de notas (frontmatter)
  • Listar notas y carpetas
  • Buscar notas por contenido o metadatos
  • Gestionar notas diarias
  • Obtener enlaces salientes, backlinks y etiquetas

Instalación

  1. Clona el repositorio (si aún no lo has hecho):

    # git clone <repository-url>
# cd OMCP

  2. Navega al directorio del proyecto:

    cd /path/to/your/OMCP

  3. Crea un entorno virtual de Python (recomendado para evitar conflictos de dependencias):

    python -m venv .venv

  4. Activa el entorno virtual:

    • En Windows PowerShell: 
      .venv\Scripts\Activate.ps1
    • En Linux/macOS: 
      source .venv/bin/activate

    (El prompt de tu terminal debería mostrar ahora (.venv) al principio)

  5. Instala el paquete y sus dependencias:

    pip install .

Configuración

Este servidor se configura mediante variables de entorno, que pueden gestionarse convenientemente usando un archivo .env en la raíz del proyecto.

  1. Copia el archivo de ejemplo:

    # From the project root directory (OMCP/)
cp .env.example .env

    (En Windows, podrías usar copy .env.example .env)

  2. Edita el archivo .env: Abre el archivo .env recién creado en un editor de texto.

  3. Establece OMCP_VAULT_PATH: Esta es la única variable obligatoria. Actualízala con la ruta absoluta a tu bóveda de Obsidian. Usa barras diagonales (/) para las rutas, incluso en Windows.

    OMCP_VAULT_PATH="/path/to/your/Obsidian/Vault"

  4. Revisa la Configuración Opcional: Ajusta las demás variables de OMCP_ para notas diarias, puerto del servidor o directorio de respaldo si es necesario. Lee los comentarios en el archivo para obtener explicaciones.

(Alternativamente, en lugar de usar un archivo .env, puedes establecer estas variables como variables de entorno reales del sistema. El servidor priorizará las variables de entorno del sistema sobre el archivo .env si ambas están configuradas.)

Ejecución Manual (para Pruebas/Depuración)

Si bien las aplicaciones cliente como Claude Desktop lanzarán el servidor automáticamente usando la configuración descrita a continuación, también puedes ejecutar el servidor manualmente desde tu terminal para pruebas directas o depuración.

  1. Asegúrate de que la Configuración esté Completa: Asegúrate de haber creado y configurado tu archivo .env como se describe en la sección de Configuración.
  2. Activa el Entorno Virtual: 
    # If not already active
.venv\Scripts\Activate.ps1
    (Usa source .venv/bin/activate en Linux/macOS)
  3. Ejecuta el script del servidor: 
    (.venv) ...> python obsidian_mcp_server/main.py

El servidor se iniciará e imprimirá la dirección en la que está escuchando (por ejemplo, http://127.0.0.1:8001). Normalmente presionarías Ctrl+C para detenerlo cuando termines de probar.

Recuerda: Si tienes la intención de usar este servidor con Claude Desktop o un lanzador similar, no debes ejecutarlo manualmente de esta manera. Configura la aplicación cliente en su lugar (consulta la siguiente sección), y ella se encargará de iniciar y detener el proceso del servidor.

Configuración del Cliente (Ejemplo: Claude Desktop)

Muchos clientes MCP (como Claude Desktop) pueden lanzar procesos de servidor directamente. Para configurar un cliente de este tipo, normalmente necesitas editar su archivo de configuración JSON (por ejemplo, claude_desktop_config.json en macOS/Linux, busca la ruta equivalente en Windows en AppData).

⚠️ Reglas Importantes de Formato JSON:

  1. Los archivos JSON no admiten comentarios (elimina cualquier comentario // o /* */)
  2. Todas las cadenas deben estar entre comillas dobles (")
  3. Las rutas de Windows deben usar barras invertidas escapadas (\\)
  4. Usa un validador JSON (como jsonlint.com) para verificar tu sintaxis

Aquí tienes un ejemplo de entrada para agregar bajo la clave mcpServers en la configuración JSON del cliente:

{
  "mcpServers": {
    "obsidian_vault": {
      "command": "C:\\path\\to\\your\\project\\OMCP\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\your\\project\\OMCP\\obsidian_mcp_server\\main.py"],
      "env": {
        "OMCP_VAULT_PATH": "C:/path/to/your/Obsidian/Vault",
        "OMCP_DAILY_NOTE_LOCATION": "Journal/Daily"
      }
    }
  }
}

Puntos Clave:

  • Reemplaza las rutas con las rutas absolutas relevantes para tu sistema
  • Para rutas de Windows en los campos command y args:
    • Usa dobles barras invertidas (\\) como separadores de ruta
    • Incluye la extensión .exe para el ejecutable de Python
  • Para rutas de Windows en el bloque env:
    • Usa barras diagonales (/) para una mejor compatibilidad
    • No incluyas la extensión .exe
  • La ruta de command debe apuntar al ejecutable python.exe dentro del .venv que creaste
  • La ruta de args debe apuntar al archivo main.py dentro de la subcarpeta obsidian_mcp_server
  • Usar el bloque env es la forma más confiable de asegurar que el servidor encuentre la ruta de tu bóveda
  • Recuerda reiniciar la aplicación cliente después de modificar su configuración JSON

Errores Comunes a Evitar:

  1. No uses barras invertidas simples en rutas de Windows
  2. No incluyas comentarios en el JSON
  3. No olvides escapar las barras invertidas en rutas de Windows
  4. No mezcles barras diagonales e invertidas en la misma ruta
  5. No olvides poner entre comillas todas las cadenas correctamente

Herramientas MCP Disponibles

  • list_folders
  • list_notes
  • get_note_content
  • get_note_metadata
  • get_outgoing_links
  • get_backlinks
  • get_all_tags
  • search_notes_content
  • search_notes_metadata
  • search_folders
  • create_note
  • edit_note
  • append_to_note
  • update_note_metadata
  • delete_note
  • get_daily_note_path
  • create_daily_note
  • append_to_daily_note

Hoja de Ruta

Para un plan de implementación detallado por fases, incluyendo consideraciones de manejo de errores, consulta el archivo ROADMAP.md.

Este proyecto se desarrolla activamente. Aquí tienes un vistazo a las funciones planificadas:

v1.x (Corto Plazo)

  • Creación de Notas Basada en Plantillas:
    • Configurar un directorio de plantillas (OMCP_TEMPLATE_DIR).
    • Implementar la herramienta create_note_from_template (usando nombre de plantilla, ruta de destino, metadatos opcionales).
    • Agregar pruebas para la creación de plantillas.
  • Creación de Carpetas:
    • Implementar la función de utilidad create_folder.
    • Implementar la herramienta MCP create_folder.
    • Agregar pruebas para la creación de carpetas.

v1.y (Mediano Plazo / Mejoras Futuras)

  • Sustitución de variables en plantillas (por ejemplo, {{DATE}}).
  • Herramienta list_templates.
  • Herramientas avanzadas de actualización de notas (por ejemplo, append_to_note_by_metadata).
  • Herramienta list_vault_structure para una vista integral de la jerarquía de la bóveda.
  • Revisión y expansión integral de pruebas.

v2.x+ (Ideas Potenciales / Largo Plazo)

  • Herramientas de Organización:
    • move_item(source, destination) (la versión inicial podría no actualizar enlaces).
    • rename_item(path, new_name) (la versión inicial podría no actualizar enlaces).
  • Herramientas de Manipulación de Contenido:
    • replace_text_in_note(path, old, new, count).
    • prepend_to_note(path, content).
    • append_to_section(path, heading, content) (Requiere análisis confiable de encabezados).
  • Herramientas de Consulta:
    • get_local_graph(path) (Combinar enlaces salientes/backlinks).
    • search_notes_by_metadata_field(key, value).
  • Herramientas de Integración de Plugins:
    • Integración con Dataview:
      • execute_dataview_query(query_type, query) - Ejecutar consultas de Dataview y obtener resultados estructurados
      • search_by_dataview_field(field, value) - Buscar notas por campos de Dataview
    • Gestión de Tareas:
      • query_tasks(status, due_date, tags) - Buscar y filtrar tareas en toda la bóveda
    • Integración con Kanban:
      • get_kanban_data(board_path) - Obtener datos estructurados de tableros kanban
    • Integración con Calendario:
      • get_calendar_events(start_date, end_date) - Consultar eventos y tareas del calendario

Preguntas Frecuentes (FAQ)

Problemas de Configuración

P: Mi servidor no puede encontrar mi bóveda. ¿Qué está mal? R: Esto suele deberse a una configuración incorrecta de la ruta. Verifica:

  1. Que OMCP_VAULT_PATH en tu archivo .env use barras diagonales (/) incluso en Windows
  2. Que la ruta sea absoluta (comience desde la raíz)
  3. Que la ruta no termine con una barra diagonal al final
  4. Que el directorio de la bóveda exista y sea accesible

P: ¿Por qué recibo errores de permisos? R: Esto suele suceder cuando:

  1. La ruta de la bóveda apunta a un directorio restringido
  2. El proceso de Python no tiene permisos de lectura/escritura
  3. La bóveda está en una carpeta sincronizada en la nube (como OneDrive) que se está sincronizando actualmente

Intenta:

  1. Mover tu bóveda a un directorio local
  2. Ejecutar el servidor con permisos elevados
  3. Verificar que tu antivirus no esté bloqueando el acceso

Problemas de Conexión del Cliente

P: Mi cliente de IA no puede conectarse al servidor. ¿Qué debería verificar? R: Verifica estos problemas comunes:

  1. Que el servidor esté realmente ejecutándose (revisa la salida de la terminal)
  2. Que el puerto en la configuración de tu cliente coincida con el puerto del servidor
  3. Que la ruta de Python en la configuración de tu cliente apunte al entorno virtual correcto
  4. Que todas las variables de entorno estén configuradas correctamente en la configuración del cliente

P: ¿Por qué recibo errores de "Conexión rechazada"? R: Esto generalmente significa:

  1. El servidor no se está ejecutando
  2. El puerto ya está en uso
  3. El firewall está bloqueando la conexión

Intenta:

  1. Verificar si el servidor se está ejecutando: netstat -ano | findstr :8001 (Windows)
  2. Probar con un puerto diferente configurando OMCP_SERVER_PORT en tu .env
  3. Desactivar temporalmente el firewall para probar

P: Recibo "[error] [obsidian_vault] Unexpected token 'S', "Starting O"... is not valid JSON". ¿Qué está mal? R: Este error ocurre cuando el archivo de configuración JSON del cliente está malformado. Causas comunes:

  1. Comas faltantes o adicionales en el JSON
  2. Barras invertidas sin escapar en rutas de Windows
  3. Comentarios en el JSON (JSON no admite comentarios)

Revisa tu archivo de configuración del cliente (por ejemplo, claude_desktop_config.json):

  1. Usa un validador JSON (como jsonlint.com) para verificar la sintaxis
  2. Para rutas de Windows, escapa las barras invertidas: "C:\\path\\to\\file"
  3. Elimina cualquier comentario (// o /* */)
  4. Asegúrate de que todas las cadenas estén correctamente entre comillas
  5. Verifica que todos los corchetes y llaves estén correctamente cerrados

Ejemplo de formato correcto de ruta de Windows:

{
  "mcpServers": {
    "obsidian_vault": {
      "command": "C:\\path\\to\\your\\project\\OMCP\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\your\\project\\OMCP\\obsidian_mcp_server\\main.py"]
    }
  }
}

P: Recibo un error de tiempo de espera agotado y un mensaje de "Servidor desconectado". ¿Qué está sucediendo? R: Este patrón de error (la inicialización tiene éxito, pero luego se agota el tiempo de espera después de 60 segundos) generalmente significa:

  1. El servidor ya se está ejecutando en otro proceso
  2. El puerto ya está en uso por otra aplicación
  3. El proceso del servidor se está terminando inesperadamente

Intenta estos pasos en orden:

  1. Verifica si hay procesos del servidor en ejecución:

    # On Windows
netstat -ano | findstr :8001
# Look for the PID and then:
taskkill /F /PID <PID>

    # On Linux/macOS
lsof -i :8001
# Look for the PID and then:
kill -9 <PID>

  2. Verifica si otras aplicaciones están usando el puerto:

    • Cierra cualquier otra aplicación que pueda usar el puerto 8001
    • Esto incluye otros servidores MCP, servidores de desarrollo o cualquier aplicación web
    • Si no estás seguro, intenta cambiar el puerto en tu .env: 
      OMCP_SERVER_PORT=8002

  3. Verifica el proceso del servidor:

    • Abre el Administrador de Tareas (Windows) o el Monitor de Actividad (macOS)
    • Busca cualquier proceso de Python relacionado con el servidor MCP
    • Finaliza cualquier proceso sospechoso

  4. Verifica los recursos del sistema:

    • Asegúrate de tener suficiente memoria y CPU disponibles
    • Verifica si algún antivirus o software de seguridad está bloqueando el proceso
    • Verifica que tu entorno de Python tenga los permisos adecuados

  5. Reinicia todo:

    • Detén la aplicación cliente
    • Termina cualquier proceso de servidor restante
    • Elimina el archivo .env y crea uno nuevo a partir de .env.example
    • Reinicia tu computadora (si los otros pasos no funcionan)
    • Comienza de nuevo con la aplicación cliente

Si el problema persiste después de intentar todos estos pasos, comparte:

  1. El registro de errores completo
  2. La salida de netstat -ano | findstr :8001 (Windows) o lsof -i :8001 (Linux/macOS)
  3. Cualquier mensaje de error de los registros de eventos de tu sistema

### Preguntas Frecuentes

P: El servidor se desconecta inmediatamente con "Server transport closed unexpectedly... process exiting early". ¿Qué está mal? **R: Este error significa que el proceso del servidor Python se bloqueó casi inmediatamente después de ser lanzado por el cliente. No es un tiempo de espera; el propio script del servidor no pudo ejecutarse o mantenerse en ejecución.

Causas comunes:

  1. Rutas incorrectas en el JSON del cliente:
    • command no apunta al python.exe correcto dentro del .venv.
    • args no apunta al script obsidian_mcp_server/main.py correcto.
    • Separadores de ruta incorrectos o escapes de barra invertida omitidos (\\) en Windows.
  2. Dependencias faltantes:
    • Los paquetes requeridos de requirements.txt no están instalados en el .venv.
    • El cliente está lanzando Python sin activar correctamente el entorno virtual.
  3. Errores de sintaxis: Un cambio reciente en el código introdujo un error de sintaxis en Python.
  4. Error crítico de configuración/permisos:
    • Error al leer el archivo .env al iniciar.
    • OMCP_VAULT_PATH inválido o inaccesible.
    • El proceso de Python carece de permisos para ejecutarse o acceder a archivos.
  5. Excepción temprana no manejada: Ocurre un error durante la configuración inicial antes de que el servidor comience a escuchar.

Pasos de solución de problemas:

  1. Verificar rutas en el JSON del cliente: Vuelva a comprobar las rutas absolutas para command y args en la configuración JSON de su cliente. Utilice barras invertidas escapadas (\\) para rutas de Windows.
  2. Probar manualmente (paso crucial):
    • Active el entorno virtual en su terminal: 
      # On Windows
.\.venv\Scripts\activate

      # On Linux/macOS
source .venv/bin/activate
    • Ejecute el servidor directamente: 
      python obsidian_mcp_server/main.py
    • Observe detenidamente cualquier mensaje de error impreso directamente en la terminal. Esto omite al cliente y a menudo revela la causa raíz (como ImportError, SyntaxError, FileNotFoundError).
  3. Verificar dependencias: Con el venv activado, ejecute pip check y pip install -r requirements.txt.
  4. Validar .env y ruta del vault: Asegúrese de que .env exista, sea legible y que OMCP_VAULT_PATH sea correcto (use barras diagonales /).
  5. Revisar cambios recientes en el código: Compruebe si hay errores de sintaxis o problemas en los archivos Python editados recientemente.

Operaciones con Notas

P: ¿Por qué no puedo crear/editar notas en ciertas carpetas? **R: Esto podría deberse a:

  1. Restricciones de seguridad de ruta (intentar escribir fuera del vault)
  2. Permisos de carpeta
  3. Bloqueos de archivo de otros procesos

Intente:

  1. Usar rutas relativas dentro de su vault
  2. Verificar los permisos de carpeta
  3. Cerrar otros programas que puedan tener los archivos abiertos

P: ¿Por qué no se guardan mis actualizaciones de notas? **R: Causas comunes:

  1. La ruta de la nota es incorrecta
  2. El formato del contenido es inválido
  3. La creación de la copia de seguridad falló

Compruebe:

  1. Que la ruta de la nota exista y sea accesible
  2. Que el contenido sea markdown válido
  3. Que el directorio de copias de seguridad tenga permisos de escritura

Notas Diarias

P: ¿Por qué mis notas diarias no se crean en la ubicación correcta? **R: Verifique:

  1. Que OMCP_DAILY_NOTE_LOCATION esté configurado correctamente en .env
  2. Que la ruta use barras diagonales
  3. Que la carpeta de destino exista
  4. Que el formato de fecha coincida con la configuración de su vault

Solución de Problemas General

P: ¿Cómo verifico si el servidor está funcionando correctamente? **R: Ejecute el cliente de prueba:

python test_client.py

Esto realizará una serie de operaciones y reportará cualquier problema.

P: ¿Dónde puedo encontrar los registros de errores? **R: Revise:

  1. La terminal donde se está ejecutando el servidor
  2. El directorio de copias de seguridad para operaciones fallidas
  3. Los registros de eventos del sistema para problemas de permisos

P: ¿Cómo restablezco todo para comenzar de nuevo? **R: Intente estos pasos:

  1. Detenga el servidor
  2. Elimine el archivo .env
  3. Cree un nuevo .env a partir de .env.example
  4. Reinicie el servidor

¡Contribuciones Bienvenidas!