obsidian-mcp-resilient-bridge

Obsidian이 세션 시작 시점에 종료되어 있거나, 재시작되었거나, 아직 실행 중이 아니었더라도 Claude Code가 Obsidian 볼트에 계속 연결되도록 유지하는 상주형 MCP 브리지입니다.

문제

Claude Code를 Obsidian에 연결하는 표준 방법은 npx mcp-remote를 http://localhost:22360로 지정하는 것입니다. 이 주소는 "Claude Code MCP" Obsidian 플러그인이 노출하는 로컬 서버입니다. 이 방법은 동작하지만 특정 방식으로 취약합니다.

• mcp-remote는 Claude Code가 세션을 시작하는 그 순간 업스트림 서버에 정확히 한 번만 연결합니다.

• 그 시점에 Obsidian이 종료되어 있거나, 세션 중 어느 지점에서든 Obsidian이 종료되거나 재시작되면 연결 시도가 실패하거나 기존 연결이 끊어집니다.

• Claude Code는 실패했거나 끊긴 MCP 서버 전송(transport)을 스스로 재연결하지 않습니다. 연결을 되살릴 수 있는 유일한 방법은 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 방향): Obsidian 플러그인의 로컬 서버를 가리키는 SSEClientTransport에 연결된 MCP Client입니다. 이 쪽은 자체 무한 재연결 루프를 실행합니다. 실패하거나 연결이 끊기면 3초를 기다린 후 다시 시도하며, 브리지 프로세스가 살아 있는 한 이 과정을 계속 반복합니다.

• Obsidian에 연결할 수 없을 때에도 Claude Code의 도구 호출은 크래시하거나 멈추지 않습니다. 대신 "지금 Obsidian이 실행 중이 아니므로 자동으로 재연결합니다"라는 명확한 오류를 담은 일반 MCP 도구 결과를 반환하므로 Claude Code는 전체 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 안에서 실행되어 http://localhost:22360에서 볼 수 있는 MCP 도구를 노출합니다. 이 저장소에 원본 상태 그대로(수정하지 않은 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에서 설정(Settings) → 커뮤니티 플러그인(Community plugins)에서 "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 에이전트가 없다면, 동일한 과정을 직접 진행할 수 있습니다.

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에서 설정(Settings) → 커뮤니티 플러그인(Community plugins)를 열고, "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의 실제 전체 경로를 사용하며, 위의 한 것 같은 자리표시자(placeholder)를 사용하지 마세요.

5. Claude Code 세션을 종료하고 다시 시작하세요. 이것은 한 번만 필요합니다. 이후 Obsidian을 닫거나 다시 열어도 다시 재시작할 필요가 없습니다.

동작 방식

구조적으로 index.mjs는 두 개의 독립적인 MCP 연결을 이어주는 하나의 Node.js 프로세스입니다.

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

• 시작 시 브리지는 즉시 StdioServerTransport를 통해 Claude Code에 연결합니다. 이 연결은 Claude Code 세션 전체에 걸쳐 유지되며, 이는 의도된 동작입니다.

• 그 다음 단 하나의 백그라운드 루프(maintainUpstreamConnection)를 실행합니다. 이 루프만이 업스트림 연결 시도를 실행할 수 있으므로, 연결 시도가 동시에 여러 개 생기지 않습니다. 연결이 끊기거나 실패하면 RECONNECT_DELAY_MS(기본값 3000ms)를 기다렸다 다시 시도하며, 이 과정을 무기한 반복합니다.

• 모든 다운스트림 MCP 요청(tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get 등)은 전달하기 전에 현재 업스트림 연결 상태를 확인합니다. 업스트림이 연결되지 않았다면 목록 계열 요청은 빈 결과로, 호출/읽기/가져오기 계열 요청은 멈추거나 예외가 아니라 명확한 오류를 반환합니다.

• 업스트림이 재연결에 성공하면, 브리지는 Claude Code에게 notifications/tools/list_changed 알림을 보내 도구 목록을 새로고침하도록 합니다.

• 모든 로그는 stderr로만 보내집니다. stdout은 Claude Code와의 JSON-RPC 프로토콜에만 사용됩니다. 다른 내용을 stdout에 출력하면 stdio 전송이 손상될 수밖에 없습니다.

• 업스트림 URL은 OBSIDIAN_MCP_URL 환경 변수로 대체할 수 있습니다. 기본값은 http://localhost:22360/sse 입니다.

라이선스

브리지 자체(index.mjs, package.json, 저장소 루트에 있는 모든 항목)는 MIT 라이선스를 따릅니다. 자세힌 내용은 LICENSE에서 확인할 수 있습니다.

obsidian-plugin/은 별도로 포함된 제3자 프로젝트이고, 0BSD 라이선스를 적용받습니다. 자세한 례분은 obsidian-plugin/LICENSE를 참고하세요. 위 항목은 루트 MIT 라이선스 대상에 포함되지 않습니다.

크레딧

obsidian-plugin/ 은 iansinnott의 "Claude Code MCP"의 Obsidian 플러그인 (원본 저장소: obsidian-claude-code-mcp, 0BSD 라이선스)를 수정 없이 번들한 것입니다. 처음으로 Obsidian가 MCP를 지원하도록 만든 것은 그 프로젝트의 공입니다. 이 리포지터리는 단지 Claude Code 쪽 연결이 보다 견고하도록 만들 수 있는 것입니다.