Servidor MCP de Obsidian

👁 npm version

obsidian-mcp-server es un servidor MCP que permite a los agentes de IA consultar, buscar y resumir documentos Markdown de una bóveda de Obsidian.

Este proyecto va más allá de la simple lectura de documentos; ofrece búsqueda híbrida local utilizando transformers.js e incluye una interfaz de usuario de agente de IA CLI interactiva para conversar directamente con la bóveda desde la terminal.

Características principales

• 🔍 Búsqueda híbrida: Combina búsqueda por palabras clave y búsqueda semántica (vectorial), proporcionando resultados óptimos mediante RRF (Reciprocal Rank Fusion) y Reranking.

• 🚀 IA local sin dependencias: Utiliza @huggingface/transformers para ejecutar modelos de incrustación (embedding) y reordenamiento (reranking) directamente dentro del proceso de Node.js (no requiere servidor API externo).

• 💬 Agente CLI integrado: Proporciona una interfaz basada en terminal para hacer preguntas sobre el contenido de la bóveda y recibir respuestas utilizando herramientas MCP. Ver detalles

• 📦 Optimización de tokens: Ofrece varios modos de compresión y límites de salida para controlar el consumo de tokens del agente de IA.

Qué puedes hacer (Herramientas MCP)

• Búsqueda integrada (vault, action="search"): Realiza búsquedas por palabras clave y por significado simultáneamente para explorar documentos relevantes.

• Lectura de documentos (vault, action="read"): Consulta el cuerpo y los metadatos de una nota específica.

• Lista completa y estado (vault, action="list_all"|"stats"): Verifica el estado general y la lista de archivos de la bóveda.

• Recopilación de contexto (vault, action="collect_context"): Genera paquetes de conocimiento de alta densidad relacionados con un tema específico.

• Carga de conocimiento (vault, action="load_memory"): Invoca instantáneas de memoria guardadas.

• Gestión de Frontmatter (generate_property|write_property): Generación y aplicación de metadatos basados en IA.

• Organización de archivos adjuntos (organize_attachments): Mueve automáticamente las imágenes dentro de los documentos a una carpeta dedicada y actualiza los enlaces.

Instalación y configuración

1. Requisitos previos

• Node.js: v22.0.0 o superior

• Bóveda de Obsidian: Debes conocer la ruta absoluta.

2. Instalación del modelo de IA local (obligatorio)

Para habilitar las funciones de búsqueda semántica y reordenamiento, debes descargar los modelos locales necesarios mediante el siguiente comando:

# 로컬 임베딩 및 리랭킹 모델 설치
npx @sunub/obsidian-mcp-server setup

O si ya tienes instalado el paquete:

obsidian-mcp-server setup

Este comando descarga los modelos Xenova/paraphrase-multilingual-MiniLM-L12-v2 (incrustación) y Xenova/bge-reranker-base (reordenamiento) y los guarda en la caché local.

3. Configuración de variables de entorno

Ejemplo de configuración del cliente MCP

En la configuración de cada cliente, modifica env.VAULT_DIR_PATH con la ruta de tu propia bóveda.

Claude Desktop / Cursor / Copilot

{
 "mcpServers": {
 "obsidian": {
 "command": "npx",
 "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
 "env": {
 "VAULT_DIR_PATH": "/Users/username/Documents/MyVault"
 }
 }
 }
}

Cómo funciona la búsqueda híbrida

Para capturar la relevancia semántica que es difícil de encontrar solo con la búsqueda por palabras clave, se sigue el siguiente proceso:

1. Búsqueda por palabras clave: Extrae resultados de coincidencia exacta mediante el Indexer interno.

2. Búsqueda vectorial: Utiliza LanceDB y las incrustaciones de transformers.js para buscar fragmentos semánticamente similares.

3. Fusión RRF: Combina las clasificaciones de ambos resultados de búsqueda mediante el algoritmo Reciprocal Rank Fusion.

4. Reordenamiento local: Evalúa nuevamente los resultados superiores combinados con el modelo BGE Reranker para determinar la clasificación final.

Si el modelo no está instalado, funcionará automáticamente en modo exclusivo de palabras clave y mostrará un mensaje recomendando ejecutar npx @sunub/obsidian-mcp-server setup en la terminal.

Interfaz de usuario de agente de IA CLI interactiva

Este proyecto incluye una interfaz de chat de IA basada en terminal optimizada para la bóveda de Obsidian.

Características

• Integración RAG: Al hacer una pregunta, recopila automáticamente el contexto relevante de la bóveda y lo envía al LLM.

• Streaming en tiempo real: Renderiza la respuesta del LLM y el "proceso de pensamiento ()" en tiempo real.

• Comandos de barra diagonal: Permite invocar herramientas MCP directamente desde la CLI, como /search, /read, /index.

• Gestión multi-MCP: Monitorea el estado y la lista de herramientas de todos los servidores MCP conectados.

Cómo ejecutar

1. Ejecutar el servidor del modelo de chat: Inicia un servidor como llama.cpp u Ollama en modo compatible con OpenAI.

   • Ejemplo: llama-server -m models/gemma-2-9b-it.Q4_K_M.gguf --port 8080

2. Ejecutar CLI:

# 환경변수와 함께 실행
VAULT_DIR_PATH="/your/vault" LLM_API_URL="http://localhost:8080" npx @sunub/obsidian-mcp-server

Ayuda de comandos de barra diagonal

• /search <palabra clave>: Ejecuta búsqueda híbrida

• /read "nombre de archivo": Leer un documento específico

• /stats: Verificar el estado de la bóveda

• /index: Forzar la reindexación de la base de datos vectorial

• /tools: Ver la lista de todas las herramientas MCP disponibles

• /help: Ver ayuda

Licencia

Apache-2.0

Maintenance

Resources

• Remote Server
• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• create_document_with_propertiesA
• generate_propertyA
• organize_attachmentsA
• vaultA
• write_propertyA