claudeaibridge

Gib claude.ai — auch im kostenlosen Tarif — ein echtes Coding-Agent-Erlebnis auf deinem eigenen Rechner: Dateibearbeitung, Shell-Zugriff, Git, alles in einem Projektordner, den du ausdrücklich selbst wählst, und vollständig aus dem Web gesteuert. Keine IDE, kein Claude Code-Abonnement, kein manuelles Kopieren-und-Einfügen von Code in den Browser.

Es funktioniert, indem ein kleiner lokaler Server das MCP-Protokoll spricht — dasselbe Protokoll, das Claude Code und Claude Desktop für Tools verwenden — und dieser Server über eine öffentliche URL (via ngrok oder eine eigene Domain bzw. einen eigenen Tunnel) als benutzerdefinierter Connector für claude.ai bereitgestellt wird. Der Zugriff ist hinter einem echten OAuth-Zustimmungsbildschirm abgesichert, den nur du — auf dieser Maschine — freigeben kannst.

Warum

claude.ai-Connectors erlauben Claude bereits, Daten in anderen Diensten (Google Drive, GitHub usw.) über entfernte MCP-Server zu lesen und zu schreiben. Dieses Projekt richtet genau diesen Mechanismus auf dein eigenes Dateisystem — also das, was Claude Code lokal tut, nur erreichbar aus einem Browser-Tab.

Related MCP server: claude-agent-mcp

Wie es abgesichert ist

Dadurch erhält eine Webseite die Möglichkeit, Dateien auf deinem Computer zu bearbeiten und Shell-Befehle auszuführen. Das Design setzt stark auf Eingrenzung statt auf Vertrauen:

• Du wählst die Ordner. Der Connector kann immer nur die Projektordner sehen, die du explizit auf dieser Maschine registriert hast (über die CLI) — er selbst kann keine neuen hinzufügen. Eine durchgesickerte Connector-URL bedeutet also nicht „Zugriff auf deine komplette Festplatte“.

• Dateisystem-Kappung. Jedes Datei-Tool löst Pfade auf und prüft sie gegen den Stamm des aktiven Projekts, bevor es das Dateisystem anfasst; ../-Traversalen und Symlink-Ausbrüche werden abgewiesen. Shell-Befehle laufen in einer Sandbox (bwrap auf Linux, sandbox-exec auf macOS), die den Rest des Dateisystems schreibgeschützt macht.

• Echte OAuth-Einwilligung. Das Verbinden ist keine reine Formsache — claude.ai muss einen OAuth-Ablauf durchlaufen, der eine Seite auf dieser Maschine öffnet, genau auflistet, welche Projekte registriert sind, und eine:Woche; ein Mensch muss „Genehmigen“ klicken. Es gibt kein stilles Gewähren.

• Undo-Sicherheit. Dateibearbeitungen erzeugen vor jeder Änderung ein Backup; Löschaktionen verschieben Dateien statt sie zu entfernen, in einem lokalen Papierkorb-Ordner. Beides liegt im eigenen .claudeaibridge/-Ordner des Projekts.

• Ein Audit-Protokoll. Jede Datei-/Shell-Aktion wird als Klartext an <project>/.claudeaibridge/audit.log angehängt — also immer beantwortbar: „Was hat Claude hier eigentlich gemacht?“

Interaktive Widgets

Auf Hosts, die das unterstützen, rendern file_write und file_edit ihre Änderung als farbigen, zeilenweisen Diff direkt im Chat — automatisch, ohne zusätzlichen Schritt. Der Diff ist standardmäßig aufgefaltet; ein Klick auf den Dateinamen faltet ihn zu oder auf. Claude erhält aber weiter exakt dieselben Ergebnisdaten (was geändert wurde, Backup-Pfad, Fehlerdetails) — das Widget ist nur eine Abbildung dieser Daten, kein Ersatz. Auf einem Host ohne Widget-Unterstützung bleibt das gewöhnliche Ergebnis des Tools unverändert.

Plattformunterstützung

Linux und macOS. Windows wird noch nicht unterstützt (für den Sandboxing-Ansatz gibt es noch keine Python-Windows-Entsprechung).

Installation

Option 1 — vorkompiliertes Binary. Erstelle dir selbst eines mit PyInstaller (siehe Aus dem Quellcode bauen) — es gibt derzeit keinen Download-Schritt, sondern nur einen Build-Schritt.

Option 2 — aus dem Quellcode, mit Python 3.10+:

git clone https://github.com/yemi-sh/claudeaibridge.git
cd claudeaibridge
python3 -m venv .venv
.venv/bin/pip install -e .

Schnellstart

claudeaibridge init

Der Assistent führt dich durch alles:

1. Ein ngrok-Authtoken (kostenlos — hier erhält du eines ), oder eine eigene Domain/einen eigenen Tunnel, falls du schon einen hast, oder nur lokal für Tests.

2. Auswahl des Projekts (er) Projektordner, in denen claude.ai arbeiten können soll, über einen interaktiven DateiBrowser (Pfeiltasten zum Navigieren, Leertaste zum Auswählen, Tippen zum Suchen).

3. Das Tool installiert als Hintergrunddienst (systemd auf Linux, launchd auf macOS) und gibt die Connect-URL aus — du bist das Terminal schließen, sie läuft.

Wechsle dann in claude.ai: Einstellungen → Connectors → "Add customconnector", füge die ausgegebene URL ein. claude.ai öffnet einen BrowserTabs zur Autorisierung — bestätige sie auf der Zustimmungsseite — und du bist verbunden. Bitte Claude, veröffentlichte Projekte auflisten, wähl eines aus out und leg los.

Prüfe den Status jederzeit mit claudeaibridge status. Falls kein Dienst-Manager verfügbar ist (Windows, oder ein Linux-Setup ohne systemd)Benutzer-Sitzung ist), weicht init auf den Vordergrund aus.

Befehlsreferenz

claudeaibridge init

Der oben beschriebene Assistent ist der Einrichtungsassistent. Das erneute Ausführen ist gefahrlos: jeder Schritt ist, was bereits konfiguriert ist und du entscheidest selbst, ob du es übernimmst. Ein wiederholtes Ausführen installiert den Hintergrund-Dienst dabei mit den neuen Angaben neu und ersetzt den alten.

claudeaibridge status

Zeigt, ob der Hintergrund-Dienst gerade läuft, und die letzte ausgegebene Connector-URL.

claudeaibridge stop

Stoppt den Hintergrund-Dienst und deinstalliert ihn (entfernt die systemd/launchd-Einheit vollständig, stoppt sie nicht nur) — der Connector geht offline, bis du init oder serve wieder ausführst.

Projects

claudeaibridge add-project ~/code/my-repo   # register a specific folder
claudeaibridge add-project                  # or pick one (or several) interactively
claudeaibridge edit-project ~/code/my-repo  # unregister that folder directly
claudeaibridge edit-project                 # or open the picker, pre-checked with
                                             # everything registered — check/uncheck
                                             # to add or remove
claudeaibridge list-projects                # print all registered paths

Die Identität deine Projekte ist der aufgelöste Dateisystempfad — es gibt keinen klaren zusätzlichen Namen, den du dir merken musst.

claudeaibridge serve

Installiert bzw. startet den MCP-Server als Hintergrund-Dienst mit den übergebenen Flags (init ruft am Ende des Assistenten denselben Pfad auf) und kehrt zurück — blockiert dein Terminal also nicht. Wenn der Hintergrund-Dienst schon läuft, gibt serve nur die bestehende Connector-URL mir wieder, statt ihn neu zu installieren.

Beispiele:

claudeaibridge serve --ngrok                                    # install+start as a service
claudeaibridge serve --base-url https://your-domain.example     # bring your own tunnel
claudeaibridge serve --no-auth --foreground                     # local-only testing, blocking
claudeaibridge serve --transport stdio                          # local MCP client

claudeaibridge ngrok

claudeaibridge ngrok set-authtoken <token>   # one-time setup
claudeaibridge ngrok status                  # check whether a token is configured

Jedes ngrok-Konto (auch der kostenlose Tarif) wird dauerhaft genau einem statischen Domain zugeordnet, und bindet sich allein mit dem authtoken automatisch daran — sonst nichts zu konfigurieren. Wenn du einen bezahlten Tarif hast und eine eigene Domain möchtest, starte einen eigenen ngrok http --domain=...-Prozess oder richte --base-url (ohne --ngrok) auf diesen claudeaibridge serve-Prozess aus.

Konfiguration

Alles liegt unter ~/.config/claudeaibridge/ (oder $XDG_CONFIG_HOME/claudeaibridge):

• projects.json — die registrierte Projekt-Zulassungsliste

• ngrok_authtoken — dein ngrok-Token (chmod 600)

• oauth_state.json — registrierte OAuth-Clients und -Tokens, Freigabe für den Connector in claude.ai ist nur einmal nötig, nicht (wie) bei jedem Neustart

• connector_url — die letzte ausgegebene Connector-URL, damit claudeaibridge status etwas anzeigen kann, selbst wenn der Server als Hintergrund-Dienst läuft (und dessen eigene stdout-Ausgabe nicht einsehbar ist)

Aus dem Quellcode bauen

pip install -e '.[build]'
./packaging/build.sh

Erstellt dist/claudeaibridge-<os>-<arch>. PyInstaller kann nicht kreuzkompilieren — dies erzeugt also nur für die Plattform, auf der du es ausführst.

Tests ausführen

pip install -e '.[test]'
python tests/smoke_test.py        # core MCP tools, in-memory
python tests/oauth_flow_test.py   # full OAuth flow against a real subprocess
python tests/tunnel_test.py       # live ngrok test — needs NGROK_AUTHTOKEN set

Bekannte Einschränkungen

• Windows wird nicht unterstützt, und der Hintergrund-Dienst Schritt von init benötigt systemd (Linux) oder launchd (macOS) — wenn keines verfügbar ist, weicht er auf die Ausführung im Vordergrund zurück.

• Den launchd (macOS)-Pfad für den Hintergrund-Dienst ist implementiert, aber unverifiziert — er wurde nur auf Linux (systemd) gebaut und getestet, da es die einzige Plattform während der Entwicklung war.

• Bisher. ein Widget: file_write/file_edit rendern Ihre jeweilige Änderung als farbigen Diff. Gegen claude.ai live bestätigt.

Lizenz

GPL-3.0-or-later.