Terminal MCP

Lass KI dein Terminal sehen und damit interagieren.

Terminal MCP gibt LLMs eine gemeinsame Sicht auf deine Terminal-Sitzung. Perfekt zum Debuggen von CLI- und TUI-Anwendungen in Echtzeit oder um KI terminalbasierte Tools autonom steuern zu lassen.

Installation

npm install -g @ellery/terminal-mcp

Oder über das Installationsskript:

curl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/install.sh | bash

Konfiguriere deine KI-Tools

Binde terminal-mcp in die MCP-Konfiguration jedes auf deinem Rechner installierten KI-Tools in einem Schritt ein:

terminal-mcp setup                      # detect & install for all detected tools
terminal-mcp setup --dry-run            # preview without writing
terminal-mcp setup --client claude-code,gemini   # specific tools only
terminal-mcp setup --uninstall          # remove the entry from each tool

Unterstützte Clients (jeder erhält das passende Schema für sein Konfigurationsformat):

Client	Konfigurationsdatei	Format
OpenAI Codex CLI	~/.codex/config.toml	TOML
GitHub Copilot CLI	~/.copilot/mcp-config.json	JSON
Gemini CLI	~/.gemini/settings.json	JSON
OpenCode	~/.config/opencode/opencode.json	JSON
Claude Code	~/.claude.json	JSON
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)	JSON

Eine .bak einer vorhandenen Konfiguration wird bei der ersten Installation neben dem Original geschrieben. Der terminal-mcp-Eintrag wird hinzugefügt, ohne andere Server oder nicht zusammenhängende Schlüssel zu beeinträchtigen; ein erneutes Ausführen von setup ist ein No-op.

Aktualisierung

npm install -g @ellery/terminal-mcp@latest

Der interaktive Modus zeigt beim nächsten Start ein Banner, wenn eine neuere Version verfügbar ist — terminal-mcp prüft die npm-Registry einmal täglich und speichert das Ergebnis zwischen. Headless- und MCP-Client-Modi prüfen oder drucken nie etwas (so bleibt MCP stdio sauber). Um vollständig zu deaktivieren, setze NO_UPDATE_NOTIFIER=1 oder übergib --no-update-notifier.

Funktionen

• Vollständige Terminal-Emulation: Verwendet xterm.js headless für präzise VT100/ANSI-Emulation
• Plattformübergreifendes PTY: Native Pseudo-Terminal-Unterstützung über node-pty (macOS, Linux, Windows)
• MCP-Protokoll: Implementiert das Model Context Protocol für die KI-Assistenten-Integration
• Sitzungsaufzeichnung: Zeichne Terminal-Sitzungen im asciicast-Format für die Wiedergabe mit asciinema auf
• Einfache API: Neun Tools für Eingabe, Beobachtung, Aufzeichnung und Sitzungslebenszyklus
• Headless-Modus: Als eigenständiger MCP-Server ohne TTY ausführbar — ideal für CI, Container und nicht-interaktive Umgebungen
• Multi-Session: Mehrere isolierte Terminal-Sitzungen in einem Prozess, adressiert über sessionId
• Sandbox-Modus: Optionale Sicherheitsbeschränkungen für Dateisystem- und Netzwerkzugriff

Aus dem Quellcode erstellen

npm install
npm run build

Verwendung

MCP-Konfiguration

Füge zu deinen MCP-Client-Einstellungen hinzu:

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp"
    }
  }
}

Mit benutzerdefinierten Optionen:

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp",
      "args": ["--cols", "100", "--rows", "30", "--shell", "/bin/zsh"]
    }
  }
}

Befehlszeilenoptionen

terminal-mcp [OPTIONS]

Options:
  --cols <number>        Terminal width in columns (default: 120)
  --rows <number>        Terminal height in rows (default: 40)
  --shell <path>         Shell to use (default: $SHELL or bash)
  --headless             Run in headless mode (embedded PTY + MCP over stdio, no TTY needed)
  --sandbox              Enable sandbox mode (restricts filesystem/network)
  --sandbox-config <path> Load sandbox config from JSON file
  --version, -v          Show version number
  --help, -h             Show help message

Recording Options:
  --record [mode]     Enable recording (default mode: always)
                      Modes: always, on-failure, off
  --record-dir <dir>  Recording output directory
                      (default: ~/.local/state/terminal-mcp/recordings)
  --idle-time-limit <sec>   Max idle time between events (default: 2s)
  --max-duration <sec>      Max recording duration (default: 3600s)
  --inactivity-timeout <sec>  Stop after no output (default: 600s)

Multi-Session Options:
  --max-sessions <n>           Max concurrent sessions (default: 5)
  --session-idle-timeout <sec> Idle non-default sessions are auto-destroyed
                               after this period (default: 600s)

Headless-Modus

Standardmäßig verwendet Terminal MCP eine Zwei-Prozess-Architektur: Du führst terminal-mcp in einem interaktiven Terminal aus (das einen Unix-Socket erstellt), dann startet dein MCP-Client eine zweite Instanz, die sich mit diesem Socket verbindet. Dies erfordert ein TTY.

Der Headless-Modus (--headless) macht diese Anforderung überflüssig, indem er intern ein eingebettetes PTY erzeugt und MCP direkt über stdio in einem einzigen Prozess bedient. Keine interaktive Terminal-Sitzung, kein Socket — nur ein eigenständiger MCP-Server mit integriertem Terminal.

Wann der Headless-Modus verwendet werden sollte

• CI/CD-Pipelines — kein TTY verfügbar
• Docker-Container — keine interaktive Shell zum parallelen Ausführen
• Remote-/Cloud-Umgebungen — MCP-Server, die von Automatisierung erzeugt werden
• Vereinfachte Einrichtung — ein Prozess, keine Socket-Koordination erforderlich

Konfiguration

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp",
      "args": ["--headless", "--cols", "120", "--rows", "40"]
    }
  }
}

So funktioniert es

MCP Client (Claude Code, etc.)
    │ STDIO (JSON-RPC)
    ▼
terminal-mcp --headless
    ├── MCP Server (stdio transport)
    ├── Terminal Emulator (@xterm/headless)
    └── Embedded PTY (node-pty)
            │
            ▼
        Shell Process (bash, zsh, etc.)

Im Headless-Modus wird die Terminal-Sitzung beim Start sofort initialisiert, sodass alle Tools (type, sendKey, getContent, takeScreenshot, startRecording, stopRecording, createSession, listSessions, destroySession) sofort verfügbar sind.

MCP-Tools

Alle Eingabe-/Ausgabetools (type, sendKey, getContent, takeScreenshot) akzeptieren ein optionales sessionId-Argument. Lasse es weg, um die Standard-Sitzung anzusprechen; übergib die von createSession zurückgegebene ID, um eine bestimmte Sitzung zu steuern.

type

Sende Texteingabe an das Terminal.

{
  "name": "type",
  "arguments": {
    "text": "echo hello"
  }
}

sendKey

Sende spezielle Tasten oder Tastenkombinationen.

{
  "name": "sendKey",
  "arguments": {
    "key": "Enter"
  }
}

Unterstützte Tasten:

• Basis: Enter, Tab, Escape, Backspace, Delete
• Pfeile: ArrowUp, ArrowDown, ArrowLeft, ArrowRight
• Navigation: Home, End, PageUp, PageDown, Insert
• Funktion: F1 bis F12
• Steuerung: Ctrl+A bis Ctrl+Z, Ctrl+C, Ctrl+D, usw.

getContent

Hole den Terminal-Puffer als Klartext.

{
  "name": "getContent",
  "arguments": {
    "visibleOnly": false
  }
}

takeScreenshot

Erfasse den Terminal-Zustand. Unterstützt drei Ausgabeformate:

Format	Beschreibung
text (Standard)	JSON mit Klartext-Inhalt, Cursorposition und Abmessungen
ansi	JSON mit erhaltenen ANSI-Farb-Escape-Sequenzen im Inhaltsfeld
png	Farb-Screenshot als PNG-Bild (erfordert @resvg/resvg-js)

{
  "name": "takeScreenshot",
  "arguments": { "format": "text" }
}

Das ansi-Format rekonstruiert SGR-Escape-Sequenzen aus dem Zellenpuffer des Terminals und erhält 16-Farben-, 256-Farben- und 24-Bit-Echtfarben-Attribute sowie Fett-, Dunkel-, Kursiv- und Unterstreichungsstile.

Das png-Format gibt einen MCP-image-Inhaltsblock mit base64-kodierten PNG-Daten zurück, gerendert mit dem One-Dark-Farbschema und macOS-ähnlicher Fensteroptik.

startRecording

Starte die Aufzeichnung der Terminal-Ausgabe in eine asciicast-v2-Datei.

{
  "name": "startRecording",
  "arguments": {
    "mode": "always",
    "idleTimeLimit": 2,
    "maxDuration": 3600
  }
}

Optionen:

• mode: always (alles speichern) oder on-failure (nur bei Nicht-Null-Exit speichern)
• outputDir: Benutzerdefiniertes Ausgabeverzeichnis
• idleTimeLimit: Maximale Sekunden zwischen Ereignissen (begrenzt Pausen bei der Wiedergabe)
• maxDuration: Automatischer Stopp nach N Sekunden
• inactivityTimeout: Automatischer Stopp nach N Sekunden ohne Ausgabe

stopRecording

Stoppe eine Aufzeichnung und finalisiere die asciicast-Datei.

{
  "name": "stopRecording",
  "arguments": {
    "recordingId": "abc123"
  }
}

createSession

Erstelle eine neue Terminal-Sitzung und gib ihre Metadaten zurück. Verwende die zurückgegebene sessionId, um diese Sitzung in nachfolgenden Tool-Aufrufen anzusprechen.

{
  "name": "createSession",
  "arguments": {
    "shell": "/bin/zsh",
    "cols": 100,
    "rows": 30
  }
}

Alle Argumente sind optional. Gibt zurück:

{
  "sessionId": "3029d",
  "shell": "/bin/zsh",
  "cols": 100,
  "rows": 30,
  "createdAt": "2026-04-25T12:58:01.072Z",
  "lastActivityAt": "2026-04-25T12:58:01.072Z",
  "isDefault": false
}

listSessions

Liste alle aktiven Sitzungen einschließlich der Standard-Sitzung auf. Meldet konfigurierte Grenzwerte.

{ "name": "listSessions", "arguments": {} }

destroySession

Zerstöre eine Sitzung anhand ihrer ID. Die Standard-Sitzung kann nicht zerstört werden.

{
  "name": "destroySession",
  "arguments": { "sessionId": "3029d" }
}

Multi-Session

Standardmäßig zielt jeder Tool-Aufruf ohne sessionId auf eine einzige automatisch erstellte Standard-Sitzung — dasselbe Verhalten, das das Projekt immer hatte. Übergib sessionId, um mehrere isolierte PTYs aus einem Prozess zu steuern.

• Die Standard-Sitzung wird bei der ersten Verwendung erstellt und kann nicht zerstört werden.
• Zusätzliche Sitzungen werden von createSession erstellt und verfolgt, bis sie zerstört oder im Leerlauf entfernt werden (--session-idle-timeout, Standard 600s).
• Gleichzeitige Sitzungen sind auf --max-sessions begrenzt (Standard 5).
• Eine aktive Aufzeichnung erfasst die Ausgabe aller Sitzungen im Prozess.

Typischer Anwendungsfall: Ein KI-Agent steuert einen lang laufenden Build in einer Sitzung, während er in einer anderen Diagnosen ausführt, ohne Befehlsverschränkung.

Sandbox-Modus

Führe das Terminal mit eingeschränktem Dateisystem- und Netzwerkzugriff aus:

# Interactive permission configuration
terminal-mcp --sandbox

# With a config file
terminal-mcp --sandbox --sandbox-config ~/.terminal-mcp-sandbox.json

Der interaktive Modus zeigt einen TUI-Dialog zur Konfiguration der Berechtigungen:

- **Lesen/Schreiben**: Voller Zugriff (aktuelles Verzeichnis, /tmp, Caches) - **Nur Lesen**: Kann lesen, aber nicht ändern (Home-Verzeichnis) - **Blockiert**: Kein Zugriff (SSH-Schlüssel, Cloud-Anmeldedaten, Auth-Tokens)

Beispiel-Konfigurationsdatei:

{
  "filesystem": {
    "readWrite": [".", "/tmp", "~/.cache"],
    "readOnly": ["~"],
    "blocked": ["~/.ssh", "~/.aws", "~/.gnupg"]
  },
  "network": {
    "mode": "all"
  }
}

Plattformunterstützung:

• macOS: Volle Unterstützung über sandbox-exec (Seatbelt)
• Linux: Volle Unterstützung über bubblewrap (erfordert bwrap installiert)
• Windows: Graceful Fallback (läuft ohne Sandbox)

Siehe Sandbox-Dokumentation für detaillierte Konfigurationsoptionen.

Aufzeichnung

Terminal MCP kann Sitzungen im asciicast-v2-Format aufzeichnen, kompatibel mit asciinema für die Wiedergabe.

Schnellstart

# Start with recording enabled
terminal-mcp --record

# Run your commands, then exit
exit

# Output shows the saved file path:
# Recordings saved:
#   ~/.local/state/terminal-mcp/recordings/20240115_143022.cast
#
# Play with: asciinema play <file>

Wiedergabe

Installiere asciinema, um Aufzeichnungen abzuspielen:

# macOS
brew install asciinema

# Linux/pip
pip install asciinema

# Play a recording
asciinema play ~/.local/state/terminal-mcp/recordings/20240115_143022.cast

# Play at 2x speed
asciinema play -s 2 recording.cast

Aufzeichnungsmodi

• always (Standard): Jede Aufzeichnung speichern
• on-failure: Nur speichern, wenn die Sitzung mit einem Nicht-Null-Code beendet wird (nützlich zum Debuggen fehlgeschlagener CI-Läufe)

# Only save recordings when something fails
terminal-mcp --record=on-failure

MCP-Tool-Aufzeichnung

KI-Assistenten können die Aufzeichnung auch programmgesteuert über MCP-Tools steuern:

1. Rufe startRecording auf, um die Erfassung zu starten
2. Führe Terminal-Operationen durch
3. Rufe stopRecording auf, um zu finalisieren und zu speichern

Dies ermöglicht KI-gesteuerte Workflows wie „diese Debugging-Sitzung aufzeichnen" oder „diese Demo erfassen".

Architektur

Terminal MCP hat drei Betriebsmodi:

Modus	Flag	Stdin	Beschreibung
Interaktiv	(Standard)	TTY	Benutzer erhält eine Shell; KI verbindet sich über Unix-Socket
Client	(Standard)	nicht-TTY	Verbindet sich mit dem Socket einer interaktiven Sitzung, bedient MCP über stdio
Headless	--headless	beliebig	Eigenständig: eingebettetes PTY + MCP-Server über stdio

Headless-Modus (empfohlen für MCP-Konfigurationen)

MCP Client (Claude Code, etc.)
    │ STDIO (JSON-RPC)
    ▼
terminal-mcp --headless
    ├── MCP SDK (@modelcontextprotocol/sdk)
    ├── Terminal Emulator (@xterm/headless)
    └── Embedded PTY (node-pty)
            │
            ▼
        Shell Process (bash, zsh, etc.)

Interaktiver + Client-Modus (Zwei-Prozess)

terminal-mcp (interactive, in your terminal)
    ├── User shell (stdin/stdout)
    └── Unix socket server (/tmp/terminal-mcp.sock)
            ▲
            │ JSON-RPC over socket
            ▼
terminal-mcp (client, spawned by MCP client)
    └── MCP server (stdio transport)

Beispiel-Sitzung

# Type a command
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"type","arguments":{"text":"ls -la"}}}

# Send Enter key
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sendKey","arguments":{"key":"Enter"}}}

# Get the output
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"getContent","arguments":{}}}

Entwicklung

npm run build    # Compile TypeScript
npm run dev      # Run with tsx (development)

Dokumentation

Siehe den docs-Ordner für detaillierte Dokumentation:

• Überblick
• Installation
• Tools-Referenz
• Aufzeichnung
• Konfiguration
• Sandbox-Modus
• Beispiele
• Architektur

Anforderungen

• Node.js 18.0.0 oder höher
• Windows 10 Version 1809 oder höher (für ConPTY-Unterstützung)

Lizenz

MIT