mcp-docker-bash

HTTP-MCP-Server mit persistenten PTY-Sessions und Hintergrund-Jobs. Agenten können interaktive Programme (htop, vim, …) steuern und deren Bildschirminhalt lesen.

Starten

docker compose up
# Erster Start: apt + pip (ca. 60 s), danach dank pip-cache schnell
# Server läuft auf http://localhost:8000

Claude Code / Desktop einbinden

mcp-config.json in die Claude-Einstellungen kopieren oder manuell eintragen:

{
  "mcpServers": {
    "bash": { "type": "http", "url": "http://localhost:8000/mcp" }
  }
}

Tools

Tool	Beschreibung
exec	Einmaliger Shell-Befehl, synchron (Timeout konfigurierbar)
pty_create	Neues persistentes Terminal öffnen → session_id
pty_send	Text/Tasten senden (\n = Enter, \x03 = Ctrl-C, \x04 = Ctrl-D)
pty_read	Aktuellen Bildschirminhalt als Zeilen-Array lesen
pty_kill	Session beenden
pty_list	Alle offenen Sessions
job_run	Hintergrund-Job starten → job_id (kehrt sofort zurück)
job_output	Output-Zeilen lesen, inkrementell per offset
job_status	Status (running/done/failed), Exit-Code, Zeilenzahl
job_kill	Job per SIGTERM beenden
job_list	Alle bekannten Jobs

Typischer PTY-Flow

pty_create → session_id
pty_send   { session_id, text: "htop\n" }
pty_read   { session_id, wait_ms: 500 }   ← gerendertes Grid, kein ANSI-Müll
pty_send   { session_id, text: "\x03" }   ← Ctrl-C
pty_kill   { session_id }

Workspace

./workspace wird als /workspace in den Container gemountet — Dateien dort sind direkt in jeder PTY-Session sichtbar.

Erweiterungspunkte

• Auth: API-Key-Header in main.py → FastAPI Depends
• Session-Cleanup: TTL-Hintergrundtask der tote PTY-Sessions aufräumt
• Streaming: SSE-Endpoint für Live-Output ohne Polling
• Ressourcenlimits: ulimit im Dockerfile oder mem_limit in docker-compose.yml