obsidian-mcp-resilient-bridge

A persistent MCP bridge that keeps Claude Code connected to your Obsidian vault even when Obsidian is closed, restarted, or wasn't running yet when the session started.

Problem

The standard way to connect Claude Code to Obsidian is npx mcp-remote pointed at http://localhost:22360, the local server the "Claude Code MCP" Obsidian plugin exposes. This works, but it's fragile in a specific way:

• mcp-remote connects to that upstream server exactly once, at the moment Claude Code starts the session.
• If Obsidian is closed at that moment, or if Obsidian is closed or restarted at any point during the session, that connection attempt fails or the existing connection drops.
• Claude Code does not reconnect a failed or dropped MCP server transport on its own. The only way to get the connection back is a full restart of the Claude Code session.

In practice: open Obsidian a few seconds after starting Claude Code, or let it crash, update, or close mid-session, and your Obsidian tools are gone until you restart the whole session.

Solution

index.mjs is a small persistent Node.js process, built on @modelcontextprotocol/sdk, that sits between Claude Code and the Obsidian plugin and never dies because of Obsidian:

• Downstream side (toward Claude Code): an MCP Server on a StdioServerTransport. This side is intentionally bulletproof - stdout is a pure JSON-RPC channel to Claude Code, and the process traps uncaughtException / unhandledRejection so nothing on the Obsidian side can ever crash it or close the stdio pipe.
• Upstream side (toward Obsidian): an MCP Client on an SSEClientTransport pointed at the Obsidian plugin's local server. This side runs its own infinite reconnect loop: on failure or disconnect, wait 3 seconds and try again, forever, for as long as the bridge process is alive.
• While Obsidian is unreachable, tool calls from Claude Code don't crash or hang - they return a normal MCP tool result with a polite "Obsidian isn't running right now, reconnecting automatically" error, so Claude just sees a tool error and can retry a moment later instead of losing the whole MCP connection.

Because the bridge itself never disconnects from Claude Code, Claude Code only needs to start it once per session. Obsidian can be closed, reopened, or restarted any number of times after that, and the bridge silently reconnects in the background within a few seconds.

What's in this repo

• index.mjs, package.json - the resilient bridge itself. Written from scratch for this repo, MIT licensed.
• obsidian-plugin/ - an included copy of the "Claude Code MCP" Obsidian plugin (id claude-code-mcp) by iansinnott, original repo obsidian-claude-code-mcp, 0BSD license. This is the plugin that actually runs inside Obsidian and exposes your vault as MCP tools on http://localhost:22360. It's bundled here as-is (unmodified main.js, manifest.json, styles.css) so that a clone of this one repo is everything you need, with no extra repo to find or trust. See obsidian-plugin/LICENSE and the Credits section below for attribution.

If you're an AI agent setting this up for someone

Follow these steps in order. Steps 1, 2, 3 and 5 you can do yourself. Step 4 is the one thing you can't do - it's a GUI click only the human can make.

1. Clone this repository into a permanent folder (not a temp directory - the config in step 5 will point at this exact path for the life of the setup):

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

2. Install dependencies:

   npm install
   

3. Install the bundled plugin into the human's vault. If you don't already know the vault path, ask the human for it. Then copy the contents of obsidian-plugin/ into <vault>/.obsidian/plugins/claude-code-mcp/, for example:

   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. Ask the human to enable the plugin manually. In Obsidian: Settings → Community plugins → find "Claude Code MCP" → toggle it on. This is a GUI action you cannot perform on their behalf.

5. Add or update the obsidian entry under mcpServers in ~/.claude.json and ~/.claude/settings.json, using the absolute path to the index.mjs you cloned in step 1:

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

6. Tell the human to restart their Claude Code session once. MCP server configuration is only read at session start, so this one restart is required. After that, they should not need to restart Claude Code again just because Obsidian was closed, reopened, or restarted - the bridge handles that on its own from now on.

Manual setup instructions for humans

If you don't have an AI agent handling this for you, the same steps by hand:

1. Clone this repo somewhere permanent (not Downloads or a temp folder):

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

2. Copy the plugin into your vault. Replace <vault> with the full path to your Obsidian vault:

   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. In Obsidian, open Settings → Community plugins, and enable "Claude Code MCP". You may need to reload plugins or restart Obsidian first for it to show up in the list.
4. Open ~/.claude.json and ~/.claude/settings.json, find the mcpServers section (or add one), and add or replace the obsidian entry with:

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

   Use the actual full path to index.mjs from step 1, not the placeholder above.
5. Quit and restart your Claude Code session. This is the only restart you should need - after this, closing or reopening Obsidian will not require another one.

How it works

Architecturally, index.mjs is a single Node process wiring together two independent MCP connections:

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

• On startup, the bridge connects its StdioServerTransport to Claude Code immediately and unconditionally. This side is expected to stay connected for the entire Claude Code session.
• It then starts a single background loop (maintainUpstreamConnection) that is the only place allowed to initiate an upstream connection attempt, so there's never more than one connect attempt in flight. On any disconnect or failed attempt, it waits RECONNECT_DELAY_MS (3000ms) and tries again, indefinitely.
• All downstream MCP requests (tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, etc.) check the live upstream connection state before forwarding. If upstream isn't connected, list-type requests degrade to empty results, and call/read/get-type requests return a clear error instead of hanging or throwing.
• When the upstream reconnects successfully, the bridge sends a notifications/tools/list_changed notification downstream so Claude Code knows to refresh its view of available tools.
• All logging goes to stderr only - stdout is reserved exclusively for the JSON-RPC protocol with Claude Code, since writing anything else there would corrupt the stdio transport.
• The upstream URL can be overridden with the OBSIDIAN_MCP_URL environment variable if your Obsidian plugin is configured to listen somewhere other than the default http://localhost:22360/sse.

License

The bridge itself (index.mjs, package.json, everything in the repo root) is MIT licensed - see LICENSE.

obsidian-plugin/ is a separate, included copy of a third-party project and is licensed under 0BSD - see obsidian-plugin/LICENSE. It is not covered by the root MIT license.

Credits

obsidian-plugin/ bundles a copy of the "Claude Code MCP" Obsidian plugin by iansinnott (original repo: obsidian-claude-code-mcp, 0BSD license), included here unmodified so the whole setup works from a single clone. All credit for making Obsidian speak MCP in the first place goes to that project - this repository just makes the Claude Code side of the connection resilient.