obsidian-mcp-resilient-bridge

Eine persistente MCP-Brücke, die Claude Code mit deinem Obsidian-Vault verbunden hält, auch wenn Obsidian geschlossen ist, neu gestartet wurde oder beim Start der Sitzung noch gar nicht lief.

Problem

Der übliche Weg, Claude Code mit Obsidian zu verbinden, ist npx mcp-remote, das auf http://localhost:22360 zeigt, den lokalen Server, den das Obsidian-Plugin „Claude Code MCP“ bereitstellt. Das funktioniert, ist aber in einer bestimmten Hinsicht fragil:

• mcp-remote verbindet sich genau einmal mit diesem Upstream-Server, und zwar in dem Moment, in dem Claude Code die Sitzung startet.

• Wenn Obsidian in diesem Moment geschlossen ist oder wenn Obsidian irgendwann während der Sitzung geschlossen oder neu gestartet wird, schlägt dieser Verbindungsversuch fehl bzw. die bestehende Verbindung bricht ab.

• Claude Code stellt einen fehlgeschlagenen oder abgebrochenen MCP-Server-Transport nicht selbst wieder her. Der einzige Weg, die Verbindung zurückzubekommen, ist ein vollständiger Neustart der Claude-Code-Sitzung.

In der Praxis: Wenn du Obsidian ein paar Sekunden nach dem Start von Claude Code öffnest oder Obsidian mitten in der Sitzung abstürzt, aktualisiert oder geschlossen wird, sind deine Obsidian-Tools verloren, bis du die gesamte Sitzung neu startest.

Related MCP server: obsidian-mcp-server

Lösung

index.mjs ist ein kleiner, persistenter Node.js-Prozess, basierend auf @modelcontextprotocol/sdk, der zwischen Claude Code und dem Obsidian-Plugin sitzt und wegen Obsidian nie stirbt:

• Downstream-Seite (in Richtung Claude Code): ein MCP-Server auf einem StdioServerTransport. Diese Seite ist absichtlich unzerstörbar – stdout ist ein reiner JSON-RPC-Kanal zu Claude Code, und der Prozess fängt uncaughtException / unhandledRejection ab, damit nichts auf der Obsidian-Seite ihn jemals abstürzen lassen oder die stdio-Pipe schließen kann.

• Upstream-Seite (in Richtung Obsidian): ein MCP-Client auf einem SSEClientTransport, der auf den lokalen Server des Obsidian-Plugins zeigt. Diese Seite betreibt eine eigene, unendliche Wiederverbindungsschleife: Nach einem Fehler oder Verbindungsabbruch wartet sie 3 Sekunden und versucht es erneut, für immer, solange der Brückenprozess läuft.

• Solange Obsidian nicht erreichbar ist, stürzen Tool-Aufrufe von Claude Code nicht ab und hängen nicht – sie geben ein normales MCP-Tool-Ergebnis mit einem freundlichen „Obsidian läuft gerade nicht, verbinde automatisch neu.“-Fehler zurück, sodass Claude Code nur einen Tool-Fehler sieht und einen Moment später erneut versuchen kann, anstatt die gesamte MCP-Verbindung zu verlieren.

Da die Brücke selbst sich nie von Claude Code trennt, muss Claude Code sie nur einmal pro Sitzung starten. Obsidian kann danach beliebig oft geschlossen, erneut geöffnet oder neu gestartet werden, und die Brücke verbindet sich innerhalb von Sekunden still im Hintergrund neu.

Was in diesem Repo enthalten ist

• index.mjs, package.json – die resiliente Brücke selbst. Von Grund auf neu für dieses Repo geschrieben, MIT-lizenziert.

• obsidian-plugin/ – eine beigefügte Kopie des „Claude Code MCP“-Obsidian-Plugins (ID claude-code-mcp) von iansinnott, ursprüngliches Repo obsidian-claude-code-mcp, 0BSD-Lizenz. Das ist das Plugin, das tatsächlich in Obsidian läuft und deinen Vault als MCP-Tools auf http://localhost:22360 bereitstellt. Es ist hier unverändert enthalten (main.js, manifest.json, styles.css), damit ein Klon dieses einen Repos alles ist, was du brauchst, ohne ein zusätzliches Repo zu suchen oder ihm vertrauen zu müssen. Zur Namensdung siehe obsidian-plugin/LICENSE und den Abschnitt „Credits“ weiter unten.

Wenn du als KI-Agent das für jemanden einrichtest

Befolge diese Schritte in der Reihenfolge. Die Schritte 1, 2, 3 und 5 kannst du selbst durchführen. Schritt 4 ist die einzige Sache, die du nicht tun kannst – es ist ein GUI-Klick, den nur der Mensch ausführen kann.

1. Klone dieses Repository in einen permanenten Ordner (kein temporäres Verzeichnis – die Konfiguration in Schritt 5 wird permanent auf genau diesen Pfad zeigen, solange das Setup besteht):

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

2. Installiere die Abhängigkeiten:

   npm install

3. Installiere das mitgelieferte Plugin in den Vault des Menschen. Wenn du den Vault-Pfad noch nicht kennst, frag den Menschen danach. Kopiere dann den Inhalt von obsidian-plugin/ in <vault>/.obsidian/plugins/claude-code-mcp/, zum Beispiel:

   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. Bitte den Menschen, das Plugin manuell zu aktivieren. In Obsidian: Einstellungen → Community-Plugins → „Claude Code MCP“ finden → den Schalter umlegen. Das ist eine GUI-Aktion, die du nicht in seinem Namen ausführen kannst.

5. Ergänze oder aktualisiere den Eintrag obsidian unter mcpServers in ~/.claude.json und ~/.claude/settings.json – mit dem absoluten Pfad zu dem index.mjs, das du in Schritt 1 geklont hast:

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

6. Sag dem Menschen, er soll seine Claude Code-Sitzung einmal neu starten. Die MCP-Server-Konfiguration wird nur beim Start einer Sitzung ausgelesen, daher ist dieser eine Neustart erforderlich. Danach sollte er Claude Code nicht nur deshalb neu starten müssen, weil Obsidian geschlossen, erneut geöffnet oder neu gestartet wurde – die Brücke übernimmt das von nun an selbst.

Manuelle Einrichtungsanleitung für Menschen

Falls kein KI-Agent das für dich übernimmt, hier die gleichen Schritte von Hand:

1. Klone dieses Repo in einen permanenten Ort (nicht Downloads oder einen Temporärordner):

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

2. Kopiele das Plugin in deinen Vault. Ersetze <vault> durch den vollständigen Pfad zu deinem 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. Öffne in Obsidian: Einstellungen → Community-Plugins und aktiviere „Claude Code MCP“. Möglicherweise musst du zuerst Plugins neu laden oder Obsidian neu starten, damit es in der Liste erscheint.

4. Öffne the ~/.claude.json und ~/.claude/settings.json, finde den mcpServers-Abschnitt (oder füge einen hinzu) und füge den Eintrag obsidian hinzu oder ersetze ihn durch:

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

   Verwende den tatsächlichen vollständigen Pfad zu index.mjs aus Schritt 1, nicht den Platzhalter oben.

5. Beende deine Claude Code-Sitzung und starte sie neu. Das ist der einzige Neustart, den du brauchst – danach erfordert das Schließen oder Wiederöffnen von Obsidian keinen weiteren.

So funktioniert es

Architektonisch ist index.mjs ein einzelner Node-Prozess, der zwei unabhängige MCP-Verbindungen miteinander verknüpft:

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

• Beim Start verbindet die Brücke ihren StdioServerTransport sofort unbedingt mit Claude Code. Diese Seite soll für die gesamte ister Squid el Claude Code-Sitzung verbunden bleiben.

• Danach startet sie eine einzige Hintergrundschleife (maintainUpstreamConnection), die einzige Stelle, die einen Upstream-Verbindungsversuch startet darf, sodass nie mehr als einen Verbindungsversuch gleichzeitig läuft. Bei jeder Trennung oder jedem fehlgeschlagenen Versuch wartet sie RECONNECT_DELAY_MS (3000 ms) und versucht erneut, unbegrenzt.

• Alle Downstream-MCP-Anfragen (tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, usw.) prüfen vor dem Weiterleiten den live-Status der Upstream-Verbindung. Ist upstream nicht verbunden, werden Listen-Anfragen auf leere Ergebnisse herabgestuft, und Aufruf-Lese-/Get-Anfragen geben einen klaren Fehler zurück, statt zu hängen oder zu scheitern.

• Wenn sich die Verbindung zum Upstream erfolgreich wieder herstellt, schickt die Brücke eine tools/list_changed-Benachrichtigung nach downstream, damit Claude Code tool view still cache wissen und sich aktualisieren kann.

• Die gesamte Protokollierung erfolgt ausschließlich auf stderr – stdout ist allein für das JSON-RPC-Protokoll mit Claude Code reserviert, denn alles andere würde den Stdio-Transport beschädigen.

• Die Upstream-URL kann über die Umgebungsvariable OBSIDIAN_MCP_URL überschrieben werden, falls dein Obsidian-Plugin so konfiguriert ist, dass es an einem anderen Ort als der Standard-http://localhost:22360/sse-URL lauscht.

Lizenz

Die Brücke selbst (index.mjs, package.json, alles im Repo-Root) ist MIT-lizenziert – siehe LICENSE.

obsidian-plugin/ ist ein separates, enthaltenes Kopum eines Drittanbieter-Projekts und ist unter 0BSD-lizenziert – siehe obsidian-plugin/LICENSE. Sie wird nicht von der MIT-Lizenz des Repo-Root abgedeckt.

Credits

obsidian-plugin/ enthält eine beigefügte Kopie des „Claude Code MCP“-Obsidian-Plugins von iansinnott (Original-Repository: obsidian-claude-code-mcp, 0BSD-Lizenz), das hier unverändert enthalten ist, damit das gesamte Setup mit einem einzigen Klon funktioniert. Die gesamte Anerkennung dafür, dass Obsidian überhaupt MCP versteht, gebührt dieses Projekts.

Dieses Repository macht lediglich die Claude-Code-Seite der Verbindung zu sein.