obsidian-mcp-resilient-bridge

一个持久的 MCP 桥接器，让 Claude Code 在 Obsidian 被关闭、被重启，或在会话开始时尚未运行时，也能保持与你的 Obsidian 库连接。

问题

将 Claude Code 接入 Obsidian 的标准方式是使用 npx mcp-remote 并指向 http://localhost:22360，这是 Obsidian 的 “Claude Code MCP” 插件暴露出的本地服务器。它能工作，但有一个很脆弱的地方：

• mcp-remote 只会在 Claude Code 启动会话的那一刻一次性连接一次上游服务器。

• 如果那时 Obsidian 未打开，或会话过程中任何时候 Obsidian 被关闭或重启，连接尝试就会失败，或已有连接断开。

• Claude Code 不会自己重连一个失败或已断开的 MCP 服务器连接。要想恢复连接，唯一办法就是完整重启 Claude Code 会话。

在实际使用中：启动 Claude Code 几秒钟后才打开 Obsidian，或让 Obsidian 在会话中崩溃、更新或关闭，你的 Obsidian 工具就会消失，直到你重启整个会话。

Related MCP server: obsidian-mcp-server

解决方案

index.mjs 是基于 @modelcontextprotocol/sdk 的小型持久 Node.js 进程，位于 Claude Code 与 Obsidian 插件之间，永远不会因为 Obsidian 而死：

• 下游侧（面向 Claude Code）：一个使用 StdioServerTransport 的 MCP Server。这一侧被设计得非常可靠——stdout 是与 Claude Code 的纯 JSON-RPC 通道，进程会捕获 uncaughtException / unhandledRejection，因此 Obsidian 侧发生的任何事都不会让进程崩溃或导致 stdio 管道关闭。

• 上游侧（面向 Obsidian）：一个使用 SSEClientTransport 的 MCP Client，指向 Obsidian 插件的本地服务器。这一侧会有自己的无限重连循环：任何失败或断开发生后，等待 3 秒再重试，只要桥接进程经常活着，就一直重试。

• 当无法访问 Obsidian 时，Claude Code 的工具调用不会崩溃或挂起——它们会返回一个正常的 MCP 工具结果，附上清晰的 “Obsidian 当前未运行，正在自动重连” 错误，因此 Claude 看到只是一个工具错误，可以稍后重试，而不至于整个 MCP 连接失效。

由于桥接本身从不与 Claude Code 断开，Claude Code 只需要每个会话启动一次。之后 Obsidian 可以被关闭、重新打开或无限多次重启，桥接器都会在几秒内在后台自动重连。

仓库内容

• index.mjs、package.json — 桥接器本身，为这个仓库全新编写，MIT 许可。

• obsidian-plugin/ — 附带的由 iansinnott 开发的 “Claude Code MCP” Obsidian 插件副本（插件 id claude-code-mcp），原始仓库是 obsidian-claude-code-mcp，采用 0BSD 许可证。它是实际跑在 Obsidian 内部并把你的库以 MCP 工具形式暴露到 http://localhost:22360 的插件。这里把它原样（未改过的 main.js、manifest.json、styles.css）打包在一起，因此只要克隆本仓库即可拥有全部所需，不再需要找或信任其他仓库。出处请见 obsidian-plugin/LICENSE 和下面的“致谢”一节。

如果你是替用户设置的 AI 代理

请在项目开始按这个顺序来做。步骤 1、2、3、5 的组件；你可以自己完成。步骤 4 是唯一你无法做的——需要在 GUI 里由人类手动点击一次。

1. 将这个仓库克隆到一个永久目录（不要临时用，因为步骤 5 的配置会在这个路径相同的地方长期生效）：

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

2. 安装依赖：

   npm install

3. 把捆绑的插件安装到用户的库中。 如果你不知道库路径，先向用户询问。然后将 obsidian-plugin/ 中的内容复制到 <vault>/.obsidian/plugins/claude-code-mcp/，例如：

   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. 请用户手动启用插件。 在 Obsidian 中：设置 → 社区插件 → 找到 “Claude Code MCP” → 开启开关。这是你无法替用户完成的 GUI 操作。

5. 在 ~/.claude.json 与 ~/.claude/settings.json 中新增或更新 mcpServers 下的 obsidian 条目，使用步骤 1 克隆到的 index.mjs 的绝对路径：

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

6. 让用户重启一次 Claude Code 会话。 MCP 服务器配置只在会话开始读取，所以这一次重启是必需的。之后，他们不再需要因为 Obsidian 被关闭、重开或重启而去重启 Claude Code——桥接器会在那之后自行接管。

人工手动设置说明

如果你没有任何 AI Agent 代劳，你可以手动执行这些同样的步骤：

1. 把这个仓库克隆到一个永久性位置（不要是 Downloads 或临时目录）：

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

2. 把插件复制到你的库中。将 <vault> 替换为你的 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. 在 Obsidian 中打开 设置 → 社区插件，然后开启 “Claude Code MCP”。你可能需要先重新加载插件或重启 Obsidian，才能让它在列表中出现。

4. 打开 ~/.claude.json 和 ~/.claude/settings.json，找到 mcpServers 部分（或自己添加），并新增/替换 obsidian 条目为一个这样的内容：

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

   请用步骤 1 里的 index.mjs 真实完整路径替换上面的占位符。

5. 退出并重启 Claude Code 会话。这是你唯一需要的一次重启；之后，关闭或重新打开 Obsidian 就无需再重启。

它是如何工作的

从架构上讲，index.mjs 是一个 Node 进程，它把两条独立的 MCP 连接起来：

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

• 启动时，桥接器立即无条件将它自己的 StdioServerTransport 连接到 Claude Code。这一侧预计将在 Claude Code 整个会话期间保持连接。

• 它还启动了一个唯一的后台循环（maintainUpstreamConnection），允许发起上游连接的只有这一个位置，所以不会同时有多个连接尝试。任何断开或失败，它都会等待 RECONNECT_DELAY_MS（3000 毫秒）后重试，无限继续。

• 所有来自 Claude Code 的下游 MCP 请求（tools/list、tools/call、resources/list、resources/read、prompts/list、prompts/get 等）在转发前都会检查上游连接是否正常。若上游未连接，list 类请求会给回空结果，call/read/get 类请求则返回清晰的错误，而不是无限挂起或抛异常。

• 当上游重新连接成功后，桥接器会向下游发送 notifications/tools/list_changed，好让 Claude Code 重新获取可用的工具。

• 所有日志都只写入 stderr —— stdout 只留给与 Claude Code 的 JSON-RPC 协议，因为 stdout 上的任何其他内容都会造成 stdio 传输崩溃。

• 如果你的 Obsidian 插件不是默认的 http://localhost:22360/sse 地址，可以通过 OBSIDIAN_MCP_URL 环境变量覆盖上游 URL。

许可证

桥接器本身（index.mjs、package.json，以及仓库根目录内的所有其他内容）采用 MIT 许可证，见 LICENSE。

obsidian-plugin/ 是单独包含的第三方项目副本，使用 0BSD 许可证，见 obsidian-plugin/LICENSE。它不受仓库根目录 MIT 许可证覆盖。

致谢

obsidian-plugin/ 捆绑的是 iansinnott 的 “Claude Code MCP” Obsidian 插件副本（原始项目：obsidian-claude-code-mcp，0BSD 许可），并原样保存，初此只需要一次克隆即可启用全部环境。让 Obsidian 说 MCP 的荣誉属于该项目——本仓库只是让 Claude Code 端更 resilient。