Vasallo94/obsidian-mcp-server

🧠 Obsidian MCP Server

Un servidor avanzado de MCP que conecta tu inteligencia artificial (Claude, IDEs) directamente con tu "Vault" en Obsidian. No es solo un lector de archivos; es un agente activo capaz de entender la estructura, seguir tus reglas de etiquetado y adoptar personalidades especializadas (Guardián, Investigador, etc.).

✨ Características Principales

🔍 Navegación y Contexto

• Mapa del Vault: Herramientas como leer_contexto_vault le dan a la IA una visión general de tu estructura de carpetas (excluyendo archivos de sistema).
• Búsqueda Semántica: Encuentra información relevante sin necesidad de recordar nombres exactos de archivos.

🤖 Sistema de Agentes Integrado

El servidor lee tu carpeta .github/agents y permite a la IA adoptar roles específicos:

• 🛡️ Guardián del Conocimiento: Mantiene el orden y la estructura. Tiene permisos especiales (mover_nota) para reorganizar tu vault.
• 🔬 Investigador: Crea notas profundas y estructuradas sobre nuevos temas.
• 🕸️ Tejedor de Conexiones: Encuentra relaciones ocultas entre tus notas.

✍️ Creación Inteligente

• Plantillas: Utiliza tus archivos de ZZ_Plantillas automáticamente, reemplazando variables como {{title}} y {{date}}.
• Smart Tagging: Antes de crear una tag, el servidor consulta las existentes (obtener_lista_etiquetas) para evitar duplicados y sinónimos.

🔒 Seguridad y Privacidad

• Protección de Datos: Bloqueo estricto de lectura/escritura en carpetas sensibles (ej: 04_Recursos/Privado).
• Validación de Rutas: Previene accesos fuera del directorio del vault.

🚀 Requisitos e Instalación

Prerrequisitos

• Python 3.11 superior
• uv (recomendado para gestión de dependencias)

Instalación

1. Clonar el repositorio:

   git clone https://github.com/usuario/obsidian-mcp-server.git
   cd obsidian-mcp-server
   

2. Instalar dependencias:

   make install
   

3. Configuración: Crea un archivo .env basado en el ejemplo:

   cp .env.example .env
   

   Edita .env y define la ruta absoluta a tu vault:

   OBSIDIAN_VAULT_PATH="/Users/tu_usuario/Desktop/Obsidian/TuVault"
   

💻 Uso

Modo Desarrollo

Para probar el servidor localmente con el inspector de MCP:

make dev

Integración con Claude Desktop

Agrega la configuración a tu archivo claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "/ruta/a/tu/python/o/uv",
      "args": [
        "run",
        "--package",
        "obsidian-mcp-server",
        "obsidian-mcp-server"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/tu_usuario/Desktop/Obsidian/TuVault"
      }
    }
  }
}

🛠️ Estructura del Proyecto

El código está organizado siguiendo estándares profesionales de ingeniería de software en Python:

obsidian-mcp-server/
├── obsidian_mcp/           # Código fuente del paquete
│   ├── tools/              # Módulos de herramientas MCP
│   │   ├── agents.py       # Lógica de agentes (.github/agents)
│   │   ├── context.py      # Análisis de estructura del vault
│   │   ├── navigation.py   # Operaciones de archivo (mover, leer)
│   │   └── ...
│   └── server.py           # Configuración del servidor FastMCP
├── tests/                  # Suite de pruebas automatizadas (pytest)
├── scripts/                # Scripts de mantenimiento y verificación
├── docs/                   # Documentación adicional
├── pyproject.toml          # Configuración unificada (ruff, pytest, deps)
└── Makefile                # Automatización de tareas de desarrollo

🧪 Pruebas y Calidad

El proyecto cuenta con un sistema robusto de CI/CD local:

🤝 Contribución

1. Haz un fork del proyecto.
2. Crea una rama para tu feature (git checkout -b feature/nueva-magia).
3. Asegúrate de que make lint y make test pasen correctamente.
4. Envía un Pull Request.

📄 Licencia

Este proyecto está bajo la licencia MIT.