DesktopBridge 🌉

Lokaler Model Context Protocol-Server für macOS. Claude (oder ein beliebiger MCP-Host) kommuniziert über stdio mit ihm und kann:

• Dateien in erlaubten Verzeichnissen lesen, schreiben, auflisten und durchsuchen

• CPU-/Speicher-/Festplatten-Statistiken, Uptime und eine redigierte Umgebung lesen

• Laufende Anwendungen auflisten

• Shell-Befehle mit getrenntem stdout/stderr, Timeouts und optionalem Fortschritts-Streaming ausführen

• Zwischenablage lesen und schreiben

• Screenshots aufnehmen und Displays auflisten

Dieser Prozess hat dieselben Betriebssystemrechte wie der Benutzer, der ihn gestartet hat. Behandle ihn so, als würdest du dem Modell ein Terminal auf deinem Mac geben, und verkleinere dann diese Schadenszone mit DESKTOP_BRIDGE_ROOTS.

Anforderungen

• macOS (Zwischenablage, Screenshots und Anwendungsliste verwenden Apple-Tools)

• Node.js 20.19+ (22 LTS empfohlen)

Related MCP server: macOS Automator MCP Server

Installation

cd desktop-bridge
npm install
npm run build
npm test

Der kompilierte Einstiegspunkt ist dist/index.js.

Mit Claude Desktop verbinden

1. Baue den Server (npm run build).

2. Öffne Claude Desktop → Einstellungen → Entwickler → Konfiguration bearbeiten.

3. Füge den Block aus claude_desktop_config.example.json ein und ersetze Pfad und Benutzernamen:

{
  "mcpServers": {
    "desktop-bridge": {
      "command": "node",
      "args": ["/Users/YOU/dev/desktop-bridge/dist/index.js"],
      "env": {
        "DESKTOP_BRIDGE_ROOTS": "/Users/YOU/Desktop,/Users/YOU/Documents,/Users/YOU/Downloads"
      }
    }
  }
}

4. Beende Claude Desktop vollständig und starte es neu.

5. Bestätige, dass desktop-bridge unter den MCP-Tools erscheint (Brücken-Symbol 🌉).

Konfigurationsdatei auf macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Mit Claude Code verbinden

claude mcp add desktop-bridge -- node /Users/YOU/dev/desktop-bridge/dist/index.js

Oder füge denselben command / args / env-Block zu ~/.claude.json hinzu.

Mit Cursor verbinden

Füge zu ~/.cursor/mcp.json (oder zum Projekt-.cursor/mcp.json) hinzu:

{
  "mcpServers": {
    "desktop-bridge": {
      "command": "node",
      "args": ["/Users/YOU/dev/desktop-bridge/dist/index.js"]
    }
  }
}

Rauchtest ohne Host

npm run inspector

Das startet den MCP Inspector gegen den gebauten stdio-Server. Rufe list_roots auf, dann get_system_info.

Logs gehen nur auf stderr. Verwende in diesem Prozess kein console.log — stdout ist der JSON-RPC-Kanal.

Umgebung

Kopiere .env.example für eine kommentierte Vorlage. Der Server liest Prozess-Umgebung (Claude-Desktop-env-Block), nicht eine .env-Datei.

Tools

Ressourcen: desktop://roots, desktop://system/info.
Prompts: inspect_desktop, find_file.

Sicherheitsmodell

• Dateien: Jeder Pfad wird mit realpath aufgelöst. Der aufgelöste Pfad muss innerhalb eines konfigurierten Roots bleiben. .., zusätzliche Schrägstriche und Symlinks, die ausbrechen, werden abgelehnt.

• Home ist kein Standard-Root. Das hält ~/.ssh und Ähnliches außer Reichweite, bis du sie absichtlich hinzufügst.

• Shell: Immer noch eine vollwertige Benutzer-Shell. Ein Befehl kann überall hin cd, selbst wenn das cwd eingeschränkt ist. Deaktiviere es mit DESKTOP_BRIDGE_ALLOW_SHELL=false, wenn du nur Datei-/Zwischenablage-/Bildschirm-Tools möchtest.

• Umgebung: Schlüssel, die Passwort/Token/Geheimnis/Schlüssel/Zugangsdaten/Cookie/Session entsprechen, werden durch [redacted] ersetzt.

• Stdio: Kein Netzwerk-Listener. Der Host startet diesen Prozess.

macOS-Berechtigungen

Wenn screencapture fehlschlägt, öffne Systemeinstellungen → Datenschutz & Sicherheit → Bildschirmaufnahme und aktiviere die Host-App, starte sie dann neu.

Entwicklung

npm run build    # tsc → dist/
npm start        # node dist/index.js (stdio)
npm test         # compile + node:test

Layout: src/lib/* (Pfadschutz, Prozess-Runner, Glob/Suche), src/tools/* (MCP-Tools), src/index.ts (stdio-Einstieg).

Home

https://home.jameymcelveen.com ist die Browser-Startseite (web/, keine zusätzlichen npm-Pakete). Anmeldung ist @mcelveen.us plus STATUS_PASSWORD.

Was es heute gibt, und die Ablage für alles, was als Nächstes kommt:

Setze die Startseite von Chrome/Safari/Firefox auf https://home.jameymcelveen.com (Browser lassen die Seite das nicht selbst tun). Session-Cookie hält 30 Tage. / fokussiert die Suche; ⌘K auch.

Push auf main führt CI aus, dann Deployment auf Vercel (die Website) und Railway (Heartbeat + gespeicherte Konfiguration).

Auf dem Mac füge zur MCP-Server-Umgebung hinzu:

DESKTOP_BRIDGE_STATUS_URL=https://home.jameymcelveen.com/api/heartbeat
DESKTOP_BRIDGE_STATUS_TOKEN=<HEARTBEAT_TOKEN>

Lizenz

MIT