second-brain-mcp

Un servidor MCP de solo lectura para cualquier bóveda de Obsidian o markdown plano, con el protocolo de recuperación aplicado por el servidor en lugar de solicitarse en prosa.

Apunta a una carpeta de notas markdown y cualquier cliente MCP (Claude Code, Claude Desktop, Cursor, lo que sea) puede consultar esa base de conocimiento a través de cuatro herramientas reguladas. El servidor es físicamente incapaz de escribir, no puede salir del directorio de la bóveda y corta la sesión tras un presupuesto estricto de lecturas de páginas.

Por qué

Las bases de conocimiento personales acaban soldadas a una sola herramienta. Las notas viven en Obsidian; el asistente de IA que podría usarlas vive en otro sitio, así que terminas copiando y pegando. Y cuando un asistente consigue acceso a los archivos, «lee solo lo que necesites» es una petición de cortesía, no una regla.

Este servidor resuelve ambas:

• Un conector, todas las aplicaciones. MCP es el USB-C de las herramientas de IA: escribe el conector de la bóveda una vez y cualquier cliente MCP puede usarlo.

• El protocolo es ley, no una sugerencia. La recuperación de índice primero, un presupuesto estricto de lecturas, el acceso de solo lectura y un sandbox de rutas se aplican en el código. Las únicas operaciones que existen son las reguladas.

Related MCP server: obsidian_mcp

Instalación

Requiere Node.js 18 o superior.

Opción A - desde npm

claude mcp add second-brain -- npx -y @nanthansr/second-brain-mcp /abs/path/to/your/vault

Ese único comando registra el servidor en Claude Code; npx descarga y ejecuta el paquete automáticamente. Para otros clientes, consulta los bloques de configuración más abajo.

Opción B - desde el código fuente

git clone https://github.com/nanthansr/second-brain-mcp
cd second-brain-mcp
npm install && npm run build
npm test   # 15-check integration suite - should end with SMOKE PASS
claude mcp add second-brain -- node /abs/path/to/second-brain-mcp/dist/index.js /abs/path/to/your/vault

Claude Desktop

Añádelo a claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "second-brain": {
      "command": "npx",
      "args": ["-y", "@nanthansr/second-brain-mcp", "/abs/path/to/your/vault"]
    }
  }
}

Cursor

Añade el mismo bloque a ~/.cursor/mcp.json (o Cursor Settings → MCP → Add new server).

¿No tienes una bóveda a mano?

Omite por completo el argumento de la bóveda y el servidor usará su bóveda de demostración ficticia incluida («Alex Rivera»): útil para probarlo en 30 segundos.

claude mcp add second-brain-demo -- npx -y @nanthansr/second-brain-mcp

Apuntar a tu bóveda de Obsidian

Tu bóveda es simplemente una carpeta: la que elegiste cuando Obsidian dijo «Open folder as vault». Pasa la ruta absoluta de esa carpeta como argumento:

Notas:

• Un index.md en la raíz de la bóveda desbloquea el flujo de índice primero (get_index): una página de catálogo con una línea por nota. Si no tienes uno, todo sigue funcionando: el modelo recurre a search_notes.

• La configuración propia de Obsidian (.obsidian/) y cualquier otra carpeta de punto son invisibles para el servidor.

• El servidor nunca modifica nada: Obsidian puede permanecer abierto mientras se ejecuta.

Uso

Una vez conectado, solo haz preguntas. Flujos típicos (de una sesión real contra la bóveda de demostración):

«¿En qué está trabajando Alex Rivera y quién es Sam?» → get_index → read_note ×3 (cada una con la marca read 1/5, read 2/5, read 3/5) → respuesta citada.

«¿Qué ha cambiado en mi bóveda esta semana?» → list_recent(days: 7) → lista con fechas, de la más reciente a la más antigua.

«¿Dónde guardo mis notas sobre precios?» → search_notes(query: "pricing") → páginas coincidentes con fragmentos con números de línea, sin gastar presupuesto.

Los clientes que admiten prompts de MCP también reciben vault-retrieval: una plantilla de comando de barra que fija el modelo al protocolo de índice primero para una pregunta determinada.

Lo que recibe el cliente

El flujo previsto refleja cómo una persona cuidadosa usa una wiki: lee el catálogo, abre las una o dos páginas que importan y responde con citas. Localizar es barato; leer consume presupuesto.

Configuración

Modelo de seguridad

• Solo lectura por construcción. No existe ninguna herramienta de escritura, edición o borrado en el código.

• Sandbox de rutas. Cada ruta se canonicaliza primero con path.resolve y luego se compara con la raíz de la bóveda: los intentos de path traversal (../…) se rechazan. Solo se pueden leer archivos .md.

• Presupuesto de páginas estricto. Tras N llamadas a read_note (5 por defecto), el servidor rechaza más lecturas y le dice al modelo que sintetice a partir de lo que ya tiene. Las lecturas fallidas no consumen presupuesto.

• Límites de tamaño. Las notas se truncan en 50KB; los resultados de búsqueda y las listas de recientes tienen un límite.

• Carpetas de punto omitidas. .obsidian, .git y otras carpetas de punto son invisibles.

• El código es público, los datos no. El repositorio contiene solo el código del servidor y una bóveda de demostración ficticia. Tu bóveda real es la carpeta que montes en tiempo de ejecución; nunca sale de tu máquina.

Preguntas frecuentes

¿Salen mis datos de mi máquina? No. El servidor se ejecuta localmente como proceso hijo de tu cliente MCP y lee archivos del disco. No contiene código de red.

¿Puede modificar o eliminar mis notas? No. No existe ninguna herramienta que escriba. Es una propiedad del código, no un ajuste.

¿Qué ocurre cuando el modelo agota el presupuesto? La sexta lectura devuelve un error que le dice al modelo que sintetice a partir de las páginas que ya tiene. Una conversación nuea recibe un presupuesto renoado.

¿Por qué la respuesta de demostración hablaba de «Alex Rivera»? Estás en la bóveda de demostración ficticia incluida. Pasa la ruta de tu propia bóveda como primer argumento.

Desarrollo

npm run build   # tsc -> dist/
npm test        # build + 15-check smoke test (spawns the real server over stdio)

La prueba de humo usa el cliente propio del SDK contra el servidor compilado: protocolo real, sin mocks. Verifica las cuatro herramientas, el recurso, el prompt, el rechazo de path traversal y que el presupuesto de lectura rechaza la lectura N+1. La CI la ejecuta en Linux y Windows, con Node 20 y 22.

¿Te preguntas por qué está construido así? Consulta docs/design-notes.md: transportes, los tres primitivos de MCP, esquemas como prompts, y las decisiones sobre sandbox y presupuesto.

Hoja de ruta

• Variante remota (streamable HTTP) para que la bóveda sea accesible desde clientes alojados, con autenticación

• Alcance opcional por carpeta (servir solo wiki/, ocultar journal/)

Contribuir

Se aceptan issues y PRs. Mantén los invariantes: sin herramientas de escritura, sin llamadas de red, y que la prueba de humo siga en verde y sin debilitarse.

Licencia

MIT · Cambios en CHANGELOG.md