obsidian-brain

obsidian-brain

Un servidor MCP de Node independiente que le brinda a Claude (y a cualquier otro cliente MCP) búsqueda semántica + grafo de conocimiento + edición de bóveda sobre una bóveda de Obsidian. Se ejecuta como un único proceso local stdio — sin plugin, sin puente HTTP, sin clave API, nada alojado. El contenido de tu bóveda nunca sale de tu máquina.

📖 Documentación completa → sweir1.github.io/obsidian-brain Plugin complementario → sweir1/obsidian-brain-plugin (opcional — desbloquea active_note, dataview_query, base_query)

Contenido — Por qué · Inicio rápido · Lo que obtienes · Cómo funciona · Plugin complementario · Solución de problemas · Versiones recientes

¿Por qué obsidian-brain?

• Funciona sin que Obsidian esté ejecutándose — a diferencia de los servidores basados en API REST local, obsidian-brain lee los archivos .md directamente desde el disco. Obsidian puede estar cerrado; tu bóveda es solo una carpeta.
• No requiere el plugin Local REST API — nada que instalar dentro de Obsidian para la experiencia principal.
• Búsqueda semántica a nivel de fragmento con recuperación híbrida RRF — incrustaciones (embeddings) a granularidad de encabezado de Markdown, fusionadas con FTS5 BM25 mediante Reciprocal Rank Fusion. Encuentra el fragmento exacto, clasifica por significado.
• El único servidor MCP de Obsidian con PageRank + Louvain + análisis de grafos — pregunta por las notas más influyentes de tu bóveda, notas puente, clústeres temáticos. Nadie más ofrece esto.
• Proveedor Ollama para incrustaciones locales de alta calidad — cambia a qwen3-embedding:0.6b, nomic-embed-text, bge-m3, etc. con una variable de entorno.
• Todo en una instalación npx — sin clonar, sin compilar, sin clave API, sin endpoint alojado. El contenido de la bóveda nunca sale de tu máquina.

Inicio rápido

Instalación en una línea (macOS + Claude Desktop)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/sweir1/obsidian-brain/main/scripts/install.sh)"

Instala Homebrew + Node 20+ si aún no los tienes, añade los enlaces simbólicos /usr/local/bin que Claude Desktop necesita, integra obsidian-brain en tu claude_desktop_config.json, abre el panel de Acceso Total al Disco para que actives Claude, y relanza Claude. Se te pedirá tu contraseña de macOS una vez (para Homebrew + los enlaces simbólicos) y la ruta de tu bóveda una vez. Todo lo demás es automático. Audita lo que hace: scripts/install.sh.

Instalación manual

Requiere Node 20+ y una bóveda de Obsidian (o cualquier carpeta de archivos .md — Obsidian en sí es opcional).

Conecta obsidian-brain a tu cliente MCP. Ejemplo para Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian-brain": {
      "command": "npx",
      "args": ["-y", "obsidian-brain@latest", "server"],
      "env": { "VAULT_PATH": "/absolute/path/to/your/vault" }
    }
  }
}

Sal de Claude Desktop (⌘Q en macOS) y relanza. Eso es todo.

[!NOTE] En el primer arranque, el servidor indexa automáticamente tu bóveda y descarga un modelo de incrustación de ~34 MB. Las herramientas pueden tardar 30–60 s en aparecer en el cliente. Los arranques posteriores son instantáneos.

[!TIP] ¿No eres desarrollador? El tutorial para macOS cubre Homebrew, Node, la corrección de PATH para apps GUI y el Acceso Total al Disco paso a paso.

Para cualquier otro cliente MCP (Claude Code, Cursor, VS Code, Jan, Windsurf, Cline, Zed, LM Studio, JetBrains AI, Opencode, Codex CLI, Gemini CLI, Warp): consulta Instalación en tu cliente MCP.

→ Referencia completa de variables de entorno: Configuración → Detalles de modelo / preajuste / Ollama: Modelo de incrustación → Migración desde el plugin de aaronsb: Guía de migración

Lo que obtienes

18 herramientas MCP agrupadas por intención:

• Buscar y leer — search, list_notes, read_note
• Entender el grafo — find_connections, find_path_between, detect_themes, rank_notes
• Escribir — create_note, edit_note, apply_edit_preview, link_notes, move_note, delete_note
• Editor en vivo (requiere plugin complementario) — active_note, dataview_query, base_query
• Mantenimiento — reindex, index_status

→ Argumentos, ejemplos y formas de respuesta: Referencia de herramientas

Cómo funciona

flowchart LR
    Client["<b>MCP Client</b><br/>Claude Desktop · Claude Code<br/>Cursor · Jan · Windsurf · ..."]

    subgraph OB ["obsidian-brain (Node process)"]
        direction TB
        SQL["<b>SQLite index</b><br/>nodes · edges<br/>FTS5 · vec0 embeddings"]
        Vault["<b>Vault on disk</b><br/>your .md files"]
        Vault -->|"parse + embed"| SQL
        SQL -.->|"writes"| Vault
    end

    Client <-->|"stdio JSON-RPC"| OB

Tanto la recuperación como las escrituras pasan por un índice SQLite: las lecturas son baratas a nivel de microsegundos, las escrituras aterrizan en disco inmediatamente y reindexan de forma incremental el archivo afectado. Las incrustaciones son a nivel de fragmento (fragmentador recursivo consciente de encabezados que preserva bloques de código + LaTeX), y el modo hybrid predeterminado de search fusiona la clasificación semántica a nivel de fragmento con FTS5 BM25 mediante Reciprocal Rank Fusion.

→ Análisis más profundo — por qué stdio, por qué SQLite, por qué incrustaciones locales: Arquitectura → Comportamiento del observador en vivo + debounces: Actualizaciones en vivo → Reindexación programada (macOS launchd / Linux systemd): Indexación programada (macOS) · (Linux)

Plugin complementario (opcional)

Un plugin opcional de Obsidian en sweir1/obsidian-brain-plugin expone el estado de ejecución en vivo de Obsidian — editor activo, resultados de Dataview, filas de Bases — a través de un endpoint HTTP en localhost. Cuando está instalado y Obsidian está ejecutándose, active_note, dataview_query y base_query se activan. Instálalo vía BRAT con el ID de repositorio sweir1/obsidian-brain-plugin.

Envía el plugin y el servidor en la misma versión major.minor — el servidor v1.7.x se empareja con el plugin v1.7.x. La deriva en versiones de parche es aceptable.

→ Modelo de seguridad, handshake de capacidades, cobertura de funciones de Dataview / Bases: Plugin complementario

Solución de problemas

Los cuatro más comunes:

• "Connector has no tools available" en Claude Desktop — normalmente el servidor falló al iniciar. Revisa ~/Library/Logs/Claude/mcp-server-obsidian-brain.log. Solución: npm install -g obsidian-brain@latest, sal de Claude (⌘Q), relanza.
• Desajuste de ERR_DLOPEN_FAILED / NODE_MODULE_VERSION — better-sqlite3 compilado contra un ABI de Node diferente. Solución: PATH=/opt/homebrew/bin:$PATH npm rebuild -g better-sqlite3.
• Vault path not configured — VAULT_PATH no está definido. Configúralo en el bloque env de la configuración de tu cliente o en el shell.
• Versión antigua cargada vía npx (tu cliente aún muestra la versión anterior tras una publicación) — caché npx obsoleta. Solución: rm -rf ~/.npm/_npx, luego reinicia tu cliente. Mantener @latest en tu configuración evita esto.

→ Guía completa de solución de problemas (observador que no se activa, índice obsoleto, ejecutar múltiples clientes, tiempos de espera, desajuste de dimensión de incrustación, ubicaciones de registros): docs/troubleshooting.md

Versiones recientes

• v1.7.24 (2026-05-16) — aviso BYOM en embeddings.md + 5 actualizaciones de devDep
• v1.7.23 (2026-05-16) — compuerta de auto-descarga BYOM Ollama + limpieza de registros + prueba unitaria SIGTERM
• v1.7.22 (2026-05-15) — stderr estructurado (NDJSON) + estado de preparación de Ollama + actualizaciones de seguridad de dependabot + prueba de integración de drenaje SIGTERM
• v1.7.21 (2026-04-27) — corrección del selector de bóveda en install.sh + ollama pull automático + pulido de docs/pruebas
• v1.7.20 (2026-04-27) — corrección de búsqueda de prefijo Ollama + 13 elementos de pulido de auditoría

→ Registro de cambios completo: docs/CHANGELOG.md · Plan futuro: docs/roadmap.md · Compilar desde el código fuente: docs/development.md

Créditos

Gracias a obra/knowledge-graph y aaronsb/obsidian-mcp-plugin por las ideas y el código en los que se basa este proyecto. También a Xenova/transformers.js (incrustaciones locales), graphology (análisis de grafos) y sqlite-vec (búsqueda vectorial en SQLite).

Proyectos relacionados

• apple-notes-brain — servidor MCP hermano para Apple Notes en macOS: leer, escribir y buscar con round-trip completo de Markdown en ambas direcciones.

Licencia

Licencia Apache 2.0 — Copyright 2026 sweir1.