obsidian-mcp-resilient-bridge

Un puente MCP persistente que mantiene Claude Code conectado a tu bóveda de Obsidian incluso cuando Obsidian está cerrado, se reinicia o aún no estaba en ejecución cuando se inició la sesión.

Problema

La forma habitual de conectar Claude Code a Obsidian es npx mcp-remote apuntado a http://localhost:22360, el servidor local que expone el plugin "Claude Code MCP" de Obsidian. Esto funciona, pero es frágil en un aspecto concreto:

• mcp-remote se conecta a ese servidor upstream exactamente una vez, en el momento en que Claude Code inicia la sesión.

• Si Obsidian está cerrado en ese momento, o si Obsidian se cierra o se reinicia en cualquier momento de la sesión, ese intento de conexión falla o la conexión existente se pierde.

• Claude Code no restablece por sí solo el transporte de un servidor MCP que ha fallado o se ha interrumpido. La única forma de recuperar la conexión es reiniciar por completo la sesión de Claude Code.

En la práctica: abre Obsidian unos segundos después de iniciar Claude Code, o deja que se bloquee, se actualice o se cierre a mitad de sesión, y tus herramientas de Obsidian han desaparecido hasta que reinicies toda la sesión.

Related MCP server: obsidian-mcp-server

Solución

index.mjs es un pequeño proceso persistente de Node.js, construido sobre @modelcontextprotocol/sdk, que se sitúa entre Claude Code y el plugin de Obsidian y nunca falla por culpa de Obsidian:

• Lado downstream (hacía Claude Code): un Server de MCP sobre un StdioServerTransport. Este lado es deliberadamente a prueba de fallos: stdout es un canal puro de JSON-RPC hacia Claude Code, y el proceso captura uncaughtException / unhandledRejection para que cualquier cosa que ocurra en el lado de Obsidian no pueda romperlo ni cerrar el canal stdio.

• Lado upstream (hacía Obsidian): un Client de MCP sobre un SSEClientTransport apuntando al servidor local del plugin de Obsidian. Este lado tiene su propio bucle de reconexión infinito: ante un fallo o una desconexión, espera 3 segundos y lo intenta de nuevo, para siempre, mientras el proceso del puente siga vivo.

• Mientras Obsidian esté inalcanzable, las llamadas de herramientas desde Claude Code no se caen ni se quedan colgadas: devuelven un resultado de herramienta MCP normal con un error educado del tipo "Obsidian no está en ejecución ahora mismo, reconectando automáticamente", de modo que Claude simplemente ve un error de herramienta y puede reintentar un momento después en lugar de perder la conexión MCP entera.

Como el puente en sí nunca se desconecta de Claude Code, Claude Code solo necesita iniciarlo una vez por sesión. Después de eso, Obsidian puede cerrarse, volver a abrirse o reiniciarse tantas veces como quieras, y el puente vuelve a conectarse en silencio en segundo plano en cuestión de segundos.

Contenido de este repositorio

• index.mjs, package.json: el propio puente resiliente. Escrito desde cero para este repositorio, con licencia MIT.

• obsidian-plugin/: una copia incluida del plugin "Claude Code MCP" para Obsidian (id claude-code-mcp) de iansinnott, repositorio original obsidian-claude-code-mcp, licencia 0BSD. Este plugin es el que se ejecuta dentro de Obsidian y expone tu bóveda como herramientas MCP en http://localhost:22360. Se incluye aquí tal cual, sin modificaciones (main.js, manifest.json, styles.css), para que te baste con un clon de este único repositorio, sin necesidad de buscar otro que sea o el que menos te dé. Consulta obsidian-plugin/LICENSE y la sección de Créditos de la parte inferior.

Si eres un agente de IA que está haciendo esta configuración para alguien

Sigue estos pasos en orden. Puedes hacer tú mismo los pasos 1, 2, 3 y 5. El paso 4 es lo único que no puedes hacer: es una acción de interfaz gráfica que solo el usuario puede llevar a cabo.

1. Clona este repositorio en una carpeta permanente (no en un directorio temporal, porque la configuración del paso 5 apuntará a esa ruta exacta durante toda la vida de la instalación):

   git clone https://github.com/nekko4044-lgtm/obsidian-mcp-resilient-bridge.git
   cd obsidian-mcp-resilient-bridge

2. Instala las dependencias:

   npm install

3. Instala el plugin incluido en la bóveda de la persona. Si aún sabes cuál es el directorio de tu bóveda, pregunta a la persona. A continuación, copia el contenido de obsidian-plugin/ dentro de <vault>/.obsidian/plugins/claude-code-mcp/, por ejemplo:

   mkdir -p "<vault>/.obsidian/plugins/claude-code-mcp"
   cp obsidian-plugin/main.js obsidian-plugin/manifest.json obsidian-plugin/styles.css "<vault>/.obsidian/plugins/claude-code-mcp/"

4. Pídele a la persona que active el plugin manualmente. En Obsidian: Ajustes → Plugins de la comunidad → busca "Claude Code MCP" → actívalo. Es una acción de interfaz gráfica que no puedes hacer en su nombre.

5. Añade o actualiza la entrada obsidian dentro de mcpServers en ~/.claude.json y ~/.claude/settings.json, con la ruta absoluta al index.mjs que has clonado en el paso 1:

   "obsidian": {
     "type": "stdio",
     "command": "node",
     "args": ["/ABSOLUTE/PATH/TO/CLONE/index.mjs"]
   }

6. Pídele a la persona que reinicie su sesión de Claude Code una vez. La configuración del servidor MCP solo se lee al inicio de la sesión, así que este único reinicio es necesario. Después de eso, no debería necesitar reiniciar Claude Codeentras, solo porque Obsidian se haya cerrado, reabierto o reiniciado: el puente se encarga de ello por su cuenta a partir de ahora.

Configuración manual, para humanos

Si no tienes un agente de IA que lo haga por ti, los mismos pasos a mano:

1. Clona este repositorio en un lugar permanente (no en Descargas ni en una carpeta temporal):

   git clone https://github.com/nekko4044-lgtm/obsidian-mcp-resilient-bridge.git
   cd obsidian-mcp-resilient-bridge
   npm install

2. Copia el plugin dentro de tu bóveda. Reemplaza <vault> por la ruta completa de tu bóveda de Obsidian:

   mkdir -p "<vault>/.obsidian/plugins/claude-code-mcp"
   cp obsidian-plugin/main.js obsidian-plugin/manifest.json obsidian-plugin/styles.css "<vault>/.obsidian/plugins/claude-code-mcp/"

3. En Obsidian, abre Ajustes → Plugins de la comunidad, y activa "Claude Code MCP". Puede que necesites recargar los plugins o reiniciar Obsidian primero para que aparezca en la lista.

4. Abre ~/.claude.json y ~/.claude/settings.json, busca la sección cada; si no hay, crea una y añade o reemplaza la entrada obsidian con:

   "obsidian": {
     "type": "stdio",
     "command": "node",
     "args": ["/full/path/to/obsidian-mcp-resilient-bridge/index.mjs"]
   }

   Usa la ruta completa real de index.mjs del paso 1, no la del ejemplo.

5. Cierra la sesión y vuelve a iniciar Claude Code. Es el único reinicio que deberías necesitar: a partir de aquí, cerrar o volver a abrir Obsidian no requerirá lo hacer otra vez.

Cómo funciona

A nivel de arquitectura, index.mjs es un único proceso Node.js que conecta dos conexiones MCP independientes:

Claude Code  <--stdio (JSON-RPC)-->  [ this bridge ]  <--SSE-->  Obsidian plugin (localhost:22360)

• En el arranque, el puente conecta su StdioServerTransport con Claude Code de inmediato y sin condiciones. Se espera que este lado permanezca conectado durante toda la sesión de Claude Code.

• Después, inicia un único bucle de segundo plano (maintainUpstreamConnection) que es el único lugar encargado de iniciar la conexión upstream, de modo que nunca hay más de un intento de conexión en vuelo. En cualquier desconexión o intento fallido, espera RECONNECT_DELAY_MS (3000 ms) y lo intenta de nuevo, indefinidamente.

• Todas las solicitudes MCP del lado downstream (tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, etc.) comprueban el estado actual de la conexión upstream antes de reenviarse. Si upstream no está conectado, las peticiones de tipo lista se degradan a resultados vacíos, y las de tipo call/read/get devuelven un error claro en lugar de quedarse colgadas o lanzar un fallo.

• Cuando upstream se reconecta correctamente, el puente envía una notificación notifications/tools/list_changed hacia downstream para que Claude Code sepa que debe renovar su vista de las herramientas disponibles.

• Todos los registros van solo a stderr: stdout está reservado exclusivamente para el protocolo JSON-RPC con Claude Code, porque escribir ahí cualquier otra cosa corrompería el transporte stdio.

• La URL upstream se puede sobreescribir con la variable de entorno OBSIDIAN_MCP_URL si tu plugin de Obsidian esta configurado para escuchar en un sitio distinto del predeterminado http://localhost:22360/sse.

Licencia

El puente en sí (index.mjs, package.json y todo lo que está en la raíz del repositorio está con licencia MIT: consulta LICENSE.

obsidian-plugin/ es una copia aparte incluida de un proyecto de terceros y está bajo licencia 0BSD: consulta obsidian-plugin/LICENSE. No está cubierto por la licencia MIT de la raíz.

Credits

obsidian-plugin/ incluye una copia del plugin de Obsidian, en un único clon: todo surge del proyecto [oshi][de], junto con nosotros. Agradecimientos...

Gracias a la vista de difundir la idea original: este repositorio únicamente hace que el lado de Claude Code de la conexión sea resistente.