🧠 Obsidian MCP Server
Un servidor avanzado de MCP (Model Context Protocol) que convierte tu vault de Obsidian en un cerebro dinámico para tu IA (Claude Desktop, Claude Code, Cursor, etc.). Mucho más que un lector de archivos: es un ecosistema de herramientas para la gestión del conocimiento, automatización y análisis semántico.
✨ Características Principales
🛠️ Ecosistema de Herramientas (30+)
El servidor expone una amplia variedad de herramientas categorizadas por su función:
- 📂 Navegación: Listado inteligente, lectura recursiva y búsqueda avanzada.
- ✍️ Creación y Edición: Uso automático de plantillas, sugerencia de ubicación y edición con preservación de metadatos.
- 📊 Análisis y Calidad: Estadísticas del vault, sincronización de etiquetas con el registro oficial y comprobación de integridad.
- 🕸️ Grafos y Conexiones: Análisis de backlinks, detección de notas huérfanas y visualización de grafos locales.
- 🤖 Skills (Agentes): Carga dinámica de personalidades/roles desde tu vault (
{vault}/.agent/skills/). - 🔍 Búsqueda Semántica (RAG): Búsquedas por significado, sugerencia de conexiones no obvias e indexación vectorial.
- 📺 YouTube: Extracción de transcripciones para alimentar tu base de conocimientos.
🤖 Inteligencia Integrada
- Arquitectura Vault-Agnostic: Independiente de la estructura de carpetas; utiliza auto-detección inteligente para encontrar plantillas y recursos.
- Seguridad: Protección estricta de carpetas sensibles mediante
.forbidden_pathsy configuración de privacidad en el vault. - Skills Personalizables: Define roles de IA en tu vault (
.agent/skills/) para tareas específicas.
🚀 Instalación Rápida
Prerrequisitos
- Python 3.11+
- uv (Recomendado)
Pasos
- Clonar:
git clone https://github.com/Vasallo94/obsidian-mcp-server.git cd obsidian-mcp-server - Instalar:
make install # Para búsqueda semántica: pip install "obsidian-mcp-server[rag]" - Configurar:
cp .env.example .env # Edita .env con la ruta absoluta a tu vault
💻 Uso
Integración con Claude Desktop
Añade esto a tu claude_desktop_config.json:
{
"mcpServers": {
"obsidian": {
"command": "uv",
"args": ["run", "obsidian-mcp-server"],
"env": {
"OBSIDIAN_VAULT_PATH": "/Ruta/A/Tu/Vault"
}
}
}
}
📚 Documentación Técnica
Para profundizar en el funcionamiento del servidor, consulta nuestras guías detalladas en la carpeta docs/:
- 🏛️ Arquitectura: Estructura modular y flujo de datos.
- 🔧 Referencia de Herramientas: Listado completo y parámetros de cada herramienta.
- ⚙️ Configuración del Servidor: Guía sobre variables de entorno y configuración técnica.
- 🤖 Configuración del Agente: Cómo organizar tu vault (
.agent/) con skills y reglas. - 🧠 Búsqueda Semántica (RAG): Cómo funciona la indexación vectorial y el modo RAG.
🛠️ Desarrollo y Calidad
| Comando | Descripción |
|---|---|
make test | Ejecuta la suite de pruebas (pytest) |
make lint | Verificación estática (Ruff + Mypy) |
make format | Formateo automático de código |
make dev | Ejecuta el inspector de MCP para pruebas en vivo |
📄 Licencia
Este proyecto está bajo la licencia MIT.