pty-mcp

Ein MCP-Server (Model Context Protocol), der KI-Agenten interaktive Terminal-Sitzungen ermöglicht – lokale Shells, SSH, serielle Schnittstellen und persistente Remote-Sitzungen, die Verbindungsabbrüche überstehen.

Entwickelt für Systemadministratoren und Netzwerktechniker, die möchten, dass KI bei der echten Server- und Geräteverwaltung hilft, nicht nur bei der Codegenerierung.

Warum

KI-Agenten führen Befehle in nicht-interaktiven Shells aus. Sie können nicht:

• Sich per SSH auf einem Server anmelden und mit laufenden Prozessen interagieren

• Sich über eine serielle Konsole mit Routern oder Switches verbinden

• Protokolle überwachen und reagieren, wenn ein bestimmtes Ereignis eintritt

• Sitzungsstatus über mehrere Befehle hinweg beibehalten

• Auf einen Neustart des Servers warten und erkennen, wann er wieder verfügbar ist

pty-mcp löst all dies durch die Bereitstellung echter PTY-Sitzungen über MCP.

Ohne pty-mcp greifen KI-Agenten auf sleep 30 && check_status-Schleifen zurück – was CPU-Zyklen und API-Aufrufe verschwendet, während sie auf Ereignisse warten. Mit wait_for blockiert der Agent serverseitig, bis das Ereignis eintritt. Weniger Polling, weniger Energie, besser für Eisbären. 🐻❄️

Anwendungsfälle

Serveradministration

# Reboot a server and wait until it's back online
create_local_session("ping myserver")
read_output(wait_for: "bytes from", timeout: 300)
→ blocks until server responds after reboot (~80s, one tool call)

Netzwerkgeräteverwaltung

# Connect to a router via serial console
create_serial_session(port: "/dev/ttyUSB0", baud: 9600)
send_input("show interfaces status")
read_output(wait_for: "\\$")

Protokollüberwachung und Alarmierung

# Watch logs and act when something happens
create_ssh_session(host: "prod", user: "admin")
send_input("tail -f /var/log/app.log")
read_output(wait_for: "ERROR|CRITICAL", timeout: 3600)
→ returns the error line + context when it appears

Lang laufende Aufgaben, die Verbindungsabbrüche überstehen

create_ssh_session(host: "server", user: "admin", persistent: true)
send_input("apt upgrade -y")
detach_session()          → close Claude Code, task continues
# Reconnect later to check result

Funktionen

Architektur

┌─────────────────────────────────────────────────────┐
│ AI Agent (Claude Code, etc.)                        │
│                                                     │
│  MCP Tools: create_local_session, send_input,       │
│             send_control, read_output, close_session │
└──────────────────────┬──────────────────────────────┘
                       │ JSON-RPC stdio
┌──────────────────────┴──────────────────────────────┐
│ pty-mcp (MCP Server)                                │
│                                                     │
│  Session Manager                                    │
│  ├── LocalSession  (local PTY via creack/pty)       │
│  ├── SSHSession    (remote PTY via x/crypto/ssh)    │
│  ├── SerialSession (serial port via go.bug.st)      │
│  └── RemoteSession (persistent via ai-tmux)         │
└─────────────────────────────────────────────────────┘

Persistent mode (ai-tmux):

  pty-mcp ──SSH──▶ ai-tmux client ──Unix socket──▶ ai-tmux server (daemon)
                                                     ├── PTY: bash
                                                     ├── PTY: ssh admin@router
                                                     └── PTY: tail -f /var/log/syslog

Schnellstart

Claude Code Plugin (empfohlen)

Installiert die Binärdatei automatisch und registriert den MCP-Server:

claude plugin marketplace add raychao-oao/pty-mcp
claude plugin install pty-mcp@pty-mcp

Starten Sie Claude Code neu – die Binärdatei wird beim Sitzungsstart automatisch heruntergeladen, starten Sie dann ein weiteres Mal neu, um sie zu aktivieren. Kein manuelles claude mcp add erforderlich.

Aktualisierung:

claude plugin marketplace update pty-mcp
claude plugin update pty-mcp@pty-mcp

Starten Sie Claude Code neu – die neue Binärdatei wird beim Sitzungsstart automatisch heruntergeladen, starten Sie dann ein weiteres Mal neu, um das Update anzuwenden.

Manuelle Installation

Einzeilige Installation + Registrierung (macOS / Linux / WSL2):

curl -fsSL https://raw.githubusercontent.com/raychao-oao/pty-mcp/main/install.sh | sh
claude mcp add pty-mcp -- /usr/local/bin/pty-mcp

Starten Sie Claude Code neu und die Tools sind verfügbar.

Download von GitHub Releases:

Gehen Sie zu Releases, laden Sie die Binärdatei für Ihre Plattform herunter und machen Sie sie ausführbar:

chmod +x pty-mcp-*
sudo mv pty-mcp-* /usr/local/bin/pty-mcp
claude mcp add pty-mcp -- /usr/local/bin/pty-mcp

Aus Quellcode bauen (erfordert Go 1.25+):

go install github.com/raychao-oao/pty-mcp@latest
claude mcp add pty-mcp -- $(go env GOPATH)/bin/pty-mcp

WSL2-Hinweise

pty-mcp funktioniert unter WSL2 sofort. Verwenden Sie die Linux-Binärdatei:

# Inside WSL2
curl -fsSL https://raw.githubusercontent.com/raychao-oao/pty-mcp/main/install.sh | sh
claude mcp add pty-mcp -- /usr/local/bin/pty-mcp

Optional: Installieren Sie ai-tmux auf Remote-Servern

Für persistente Sitzungen, die SSH-Verbindungsabbrüche überstehen, installieren Sie ai-tmux auf Ihrem Remote-Server:

# Download for your server's architecture
curl -fsSL https://raw.githubusercontent.com/raychao-oao/pty-mcp/main/install.sh | sh
# Or just copy the binary:
scp /usr/local/bin/ai-tmux your-server:/usr/local/bin/ai-tmux

Anwendungsbeispiele

Sobald registriert, kann der KI-Agent diese MCP-Tools verwenden:

Lokale interaktive Shell:

create_local_session()                    → {session_id, type: "local"}
send_input(session_id, "cd /tmp && ls")   → {output: "...", is_complete: true}
send_input(session_id, "python3")         → start Python REPL
send_input(session_id, "print('hello')")  → {output: "hello\n>>>"}
send_control(session_id, "ctrl+d")        → exit Python
close_session(session_id)

SSH zu Remote-Server:

create_ssh_session(host: "myserver", user: "admin")
send_input(session_id, "top")
send_control(session_id, "ctrl+c")        → stop top

Auf Muster warten (v0.2.0):

create_local_session("ping myserver")
read_output(session_id, wait_for: "bytes from", timeout: 300)
→ blocks until server responds or 5 min timeout

send_input(session_id, "docker-compose up")
read_output(session_id, wait_for: "ready|error", timeout: 60, context_lines: 3)
→ returns matched line + 3 lines of context

Geheimnis / Passwort senden (v0.3.0):

# AI detects a password prompt, calls send_secret instead of handling the password itself
create_ssh_session(host: "router", user: "admin")
read_output(session_id, wait_for: "Password:")   → session is waiting for input

send_secret(session_id, prompt: "Router admin password:")
→ native GUI dialog appears on the operator's screen (macOS: system dialog,
   WSL2: Windows Get-Credential, Linux: zenity/kdialog)
→ operator types password — it is sent directly to the PTY session
→ AI only sees: {success: true, length: 12}
→ password never appears in AI context or logs

Persistente Sitzung (übersteht SSH-Verbindungsabbruch):

create_ssh_session(host: "server", user: "admin", persistent: true)
send_input(session_id, "make build")      → start long build
detach_session(session_id)                → disconnect, build continues

# Later (even after restart):
list_remote_sessions(host: "server", user: "admin")  → see running sessions
create_ssh_session(host: "server", user: "admin", session_id: "abc123")  → reattach
send_input(session_id, "echo $?")         → check build result

MCP-Tools

¹ send_secret Plattformunterstützung: macOS verwendet einen nativen Passwort-Dialog (osascript). WSL2 verwendet powershell.exe Get-Credential (Windows GUI-Dialog). Linux mit einem Display-Server verwendet zenity oder kdialog. Headless Linux greift auf /dev/tty zurück.

Audit-Protokoll

pty-mcp enthält eine optionale Audit-Protokoll-Funktion, die jeden send_input-Befehl an einen zentralen Kollektor aufzeichnet. Dies ermöglicht es Teams, zu überprüfen und nachzuvollziehen, was KI-Agenten während einer Sitzung getan haben.

Wichtig: Dies ist ein freiwilliges, selbstberichtendes Betriebsprotokoll. Es beruht darauf, dass die Bediener sich entscheiden, es zu aktivieren und den Kollektor auszuführen. Da pty-mcp auf dem eigenen Rechner des Bedieners läuft, gibt es keinen technischen Mechanismus, um die Protokollierung zu erzwingen – ein nicht konformer Bediener könnte pty-mcp einfach ohne aktiviertes Audit ausführen. Diese Funktion bietet Rückverfolgbarkeit für Teams, die dies wünschen, aber sie ist kein Ersatz für systemweite Audit-Tools (z. B. auditd, syslog-Weiterleitung, SSH-Sitzungsaufzeichnung) in Umgebungen, in denen Audit-Compliance erforderlich ist.

Was aufgezeichnet wird

• Zeitstempel, Bedieneridentität, Sitzungs-ID, Sitzungstyp (lokal/ssh/seriell), Ziel-Host

• Die exakte Eingabe, die über send_input gesendet wurde (einschließlich raw=true-Eingaben wie Menüauswahlen)

• Ausgabeschnipsel (erste 2 KB) nach jedem Befehl

• Eine cmd_id, die den Befehl mit seiner Ausgabe verknüpft

send_secret wird niemals protokolliert – Geheimnisse, die über den GUI-Dialog eingegeben werden, erscheinen nicht im Audit-Protokoll.

Einrichtung

Jeder Bediener führt dies einmal aus, um seine Konfiguration zu erstellen und ein Token zu generieren:

pty-mcp audit init

Dies erstellt ~/.config/pty-mcp/config (chmod 600) mit einem zufällig generierten Token und gibt das Token aus, um es mit dem Kollektor-Administrator zu teilen.

Der Kollektor-Administrator startet den Server (unter Verwendung des Tokens aus der Init-Ausgabe):

PTY_MCP_AUDIT_TOKEN=<token-from-init> \
  pty-mcp audit serve --port 9099 --log /var/log/pty-mcp-audit.jsonl

Audit aktivieren, nachdem die Kollektor-URL in der Konfiguration festgelegt wurde:

# Edit config and set: audit-url=http://your-collector:9099
pty-mcp audit enable
# Restart Claude Code to apply

Um die Protokollierung vorübergehend zu stoppen, ohne die Konfiguration zu verlieren:

pty-mcp audit disable

Bediener ohne Konfigurationsdatei sind nicht betroffen – Audit ist standardmäßig deaktiviert.

Audit-Modi

Protokolle überprüfen

Protokolle werden als JSONL gespeichert (ein JSON-Objekt pro Zeile), lesbar mit Standard-Tools:

# All commands by operator ray
grep '"user":"ray"' /var/log/pty-mcp-audit.jsonl | jq .

# Commands sent to a specific host
jq 'select(.target == "root@prod01")' /var/log/pty-mcp-audit.jsonl

ai-tmux: Persistenter Terminal-Daemon

ai-tmux ist ein leichtgewichtiger Daemon, der auf Remote-Servern läuft und PTY-Sitzungen über SSH-Verbindungsabbrüche hinweg am Leben erhält. Betrachten Sie es als ein für KI-Agenten entwickeltes tmux.

Auf Remote-Server installieren

# Cross-compile for Linux
GOOS=linux GOARCH=amd64 go build -o ai-tmux-linux ./cmd/ai-tmux/

# Copy to server
scp ai-tmux-linux server:~/ai-tmux
ssh server "chmod +x ~/ai-tmux && sudo mv ~/ai-tmux /usr/local/bin/ai-tmux"

Funktionsweise

• ai-tmux server – Daemon-Modus, lauscht auf Unix-Socket, verwaltet PTY-Sitzungen

• ai-tmux client – Bridge-Modus, leitet JSON-Protokoll über stdin/stdout weiter (wird von pty-mcp über SSH verwendet)

• ai-tmux list – listet aktive Sitzungen auf

Der Daemon startet automatisch, wenn pty-mcp mit persistent: true verbindet. Sitzungen werden nach 30 Minuten Inaktivität beendet.

Unterstützung für SSH-Konfiguration

pty-mcp liest ~/.ssh/config, um Host-Aliase aufzulösen:

# ~/.ssh/config
Host myserver
    HostName 192.168.1.100
    User admin
    Port 2222
    IdentityFile ~/.ssh/id_ed25519

create_ssh_session(host: "myserver", user: "admin")
# Automatically resolves hostname, port, and identity file

Anforderungen

• Go 1.25+

• Für seriell: entsprechende Geräteberechtigungen

• Für persistente Sitzungen: ai-tmux-Binärdatei auf dem Remote-Server

Changelog

Siehe CHANGELOG.md für die Versionshistorie.

Lizenz

MIT