Command-Line MCP Server

Ein Remote-Model Context Protocol-Server, der ein einziges Tool, run_command, bereitstellt, das es Claude (über die Connectors-Funktion von Claude Desktop) ermöglicht, Shell-Befehle auf dem Rechner auszuführen, auf dem dieser Server läuft.

Der Server implementiert OAuth 2.1 (Dynamic Client Registration + PKCE), weil Claude Desktop Connectors zwingend einen OAuth-Handshake erfordern – ein Connector ohne Auth-Server wird bei der Anmeldung abgelehnt. Dieser Server genehmigt die Autorisierung automatisch (keine Benutzerabfrage), was für einen persönlichen, über einen Tunnel exponierten Server in Ordnung ist.

⚠️ Sicherheitswarnung: Jeder, der diesen Server erreichen und den (automatischen) OAuth-Flow abschließen kann, kann beliebige Befehle als der Benutzer ausführen, der ihn betreibt. Setzen Sie ihn nur über einen privaten Tunnel (cloudflared / ngrok) ein und niemals in einem öffentlichen Netzwerk.

So funktioniert es

• Transport: Streamable HTTP (der Transport, den Claude Desktop Connectors erfordern).

• Zustandslos: Jede Anfrage erzeugt eine frische Server-/Transport-Instanz (kein Session-Store nötig).

• Endpunkt: POST /mcp

• Health-Check: GET /health

Tools

run_command

Führt einen Shell-Befehl aus. Unter Windows ist die Standard-Shell cmd.exe (verwenden Sie dir, cd, nicht ls/pwd), es sei denn, Sie übergeben shell: "powershell".

get_info

Gibt Betriebssystem, Architektur, Standard-Shell (cmd.exe unter Windows) und das aktuelle Arbeitsverzeichnis zurück – einmal aufrufen, damit der Client weiß, welche Shell er verwenden soll.

read_file

Liest eine Textdatei (optionaler offset/limit-Zeilenbereich). path ist absolut oder relativ zum cwd.

list_files

Listet ein Verzeichnis auf. recursive: true durchläuft den Baum (Tiefe auf 4 begrenzt).

edit_file

Exakter String-Ersatz – die bevorzugte Methode zum Bearbeiten von Code (kein Shell-Escaping nötig). path, old_text, new_text, optional replace_all. old_text muss eindeutig sein, es sei denn, replace_all ist gesetzt. Gibt einen kurzen Diff zurück.

apply_patch

Wendet einen Unified Diff über git apply an (mit einem --3way-Fallback). cwd = Repo-Root, patch = Diff-Text.

write_file

Schreibt vollständigen Inhalt in eine Datei (overwrite oder append).

batch_read

Liest mehrere Dateien in einem Aufruf. files: Array von { path, offset?, limit? }.

batch_edit

Wendet viele exakte Text-Änderungen auf eine oder mehrere Dateien in einem einzigen Aufruf an. Transaktional: Jedes old_text wird validiert, bevor eine Datei geschrieben wird, sodass ein fehlender/mehrdeutiger Treffer die gesamte Stapelverarbeitung abbricht (nichts wird geändert). Jede Änderung: { path, old_text, new_text, replace_all? }.

Nativer Git-Passthrough

git_status (-sb), git_diff (staged + paths-Optionen), git_log (max_count, revision), git_show (revision). Jeder nimmt ein optionales cwd entgegen.

Alle Dateipfade werden auf dem Host aufgelöst, auf dem der Server läuft – sie zeigen auf diesen Rechner, nicht auf Claudes Sandbox.

Lokal ausführen

npm install
npm start
# server listens on http://localhost:3000/mcp

Optionale Umgebungsvariablen: PORT, CMD_TIMEOUT_MS, CMD_MAX_BUFFER.

npm start führt start.js aus, das Port 3000 freigibt (tötet jeden Prozess, der ihn belegt), bevor der Server gestartet wird, sodass Sie nie auf EADDRINUSE stoßen.

Für Claude Desktop verfügbar machen

Option A – Cloudflare Worker (stabile URL, kein trycloudflare, keine Domain nötig)

Ein kleiner lokaler Agent hält eine WebSocket-Verbindung zu einem Cloudflare Worker offen, der zu Ihrem stabilen öffentlichen *.workers.dev-MCP-Endpunkt wird. Der Worker leitet nur an Ihren Rechner weiter, während der Agent (authentifiziert mit PROXY_SECRET) verbunden ist.

1. wrangler login (kostenloses Cloudflare-Konto).

2. Bereitstellen: wrangler deploy → notieren Sie Ihre URL, z. B. https://command-line-mcp.<subdomain>.workers.dev.

3. Setzen Sie das Geheimnis (derselbe Wert, der bereits in Ihrer gitignored .dev.vars steht): wrangler secret put PROXY_SECRET (fügen Sie das PROXY_SECRET aus .dev.vars ein).

4. Richten Sie den Agenten auf den bereitgestellten Worker aus: Setzen Sie WORKER_URL in .dev.vars auf diese URL.

5. Führen Sie auf Ihrem Rechner beides aus:

   npm start          # the MCP server on :3000
   npm run agent      # connects to the Worker with the secret

6. In Claude Desktop: Customize → Connectors → Add custom connector, fügen Sie https://command-line-mcp.<subdomain>.workers.dev/mcp ein.

Lokales Testen ohne Bereitstellung: wrangler dev --port 8787 (Worker auf :8787), dann npm run agent – der Agent liest WORKER_URL aus .dev.vars.

Option B – cloudflared / ngrok-Tunnel (ephemere URL)

Claude Desktop Connectors benötigen eine HTTPS-URL, also führen Sie den Server lokal aus und tunneln Sie ihn:

cloudflared tunnel --url http://localhost:3000 --protocol http2
# or: ngrok http 3000

Kopieren Sie die generierte https://…-URL und hängen Sie /mcp an, z. B. https://abc-123.trycloudflare.com/mcp.

Zu Claude Desktop hinzufügen

1. Öffnen Sie Customize → Connectors → Add custom connector.

2. Fügen Sie die URL (mit /mcp) ein, z. B. die Worker-URL aus Option A.

3. Benennen Sie sie Command-Line.

4. Speichern. Claude entdeckt die OAuth-Metadaten, registriert einen Client und öffnet einen Browser für den (automatisch genehmigenden) Autorisierungs-Endpunkt, leitet dann zurück und ist bereit. Es muss keine "OAuth Client ID" manuell eingegeben werden – DCR übernimmt das.

Testen ohne Claude

Verwenden Sie den MCP Inspector:

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP, URL: http://localhost:3000/mcp

Härtung (für nicht-persönliche Nutzung)

OAuth ist bereits implementiert (siehe oauthProvider.js). Für alles über einen persönlichen Tunnel hinaus sollten Sie:

1. Die automatisch genehmigende authorize() durch einen echten Zustimmungsbildschirm ersetzen oder zumindest eine Whitelist von Redirect-URIs / Clients verwenden.

2. Clients/Tokens persistieren (derzeit im Speicher – sie werden bei einem Neustart zurückgesetzt).

3. Hinter einer stabilen HTTPS-Domain hosten (z. B. einem VPS, Cloudflare Workers, Fly.io).

4. Eine Whitelist erlaubter Befehle in Betracht ziehen, um den Schadensradius zu begrenzen.

Lizenz

MIT