Interaktive Shell MCP

MCP-Server für interaktive Shell-Sitzungen mit TUI-Unterstützung. Bietet KI-Agenten persistente Terminals, interaktive Prompt-Navigation, gerendertes Bildschirmlesen und Ausgabesuche.

Demo

Warum existiert dies?

Die meisten KI-Coding-Tools führen Shell-Befehle isoliert aus: Jeder Befehl startet eine neue Shell, interaktive Prompts sind unmöglich und TUI-Apps geben nur rohe Escape-Codes aus. Dieser MCP-Server bietet persistente PTY-Sitzungen mit einem virtuellen Terminal-Emulator (@xterm/headless), sodass Agenten den Shell-Zustand beibehalten, mit den Pfeiltasten durch interaktive Prompts navigieren und gerenderte Terminalbildschirme als sauberen Text lesen können.

Drei Ausgabemodi:

Schnellstart

git clone https://github.com/lightos/interactive-shell-mcp.git
cd interactive-shell-mcp
npm install && npm run build
claude mcp add interactive-shell node dist/src/server.js

Fragen Sie dann Claude: "Überwache htop und sag mir, was am meisten CPU verbraucht"

Funktionen

• Gerendertes Bildschirmlesen von TUI-Apps via @xterm/headless

• waitForIdle über alle Lesetools hinweg (kein Raten mehr mit sleep)

• Bildschirmsuche mit Text- und Regex-Musterabgleich

• Extraktion rechteckiger Bereiche mit Zeilen-/Spaltenkoordinaten

• Shell-Allowlist: bash, zsh, fish, sh, dash, ksh, powershell.exe, pwsh, cmd.exe

• Automatische Bereinigung nach 10 Minuten Leerlauf, Erkennung des Exit-Codes für 60 Sekunden nach Prozessbeendigung

• Plattformübergreifend: Unix/Linux/macOS + Windows

Anwendungsfälle

• Interaktives Scaffolding & Migrationen: npx create-next-app, drizzle-kit push, prisma migrate, npm init oder jede inquirer/clack-basierte CLI

• Systemüberwachung: htop, btop, top, iftop, duf mit Prozesssuche und Bereichsextraktion

• DevOps TUIs: lazydocker, lazygit, k9s, terraform console

• Remote-Sitzungen: ssh auf Server, einschließlich verschachtelter TUI-Apps über SSH

• Datenbank-CLIs: psql, mysql, redis-cli, mongosh im interaktiven Modus

• Netzwerk-Tools: netcat/ncat, nmap, airodump-ng, tcpdump

• REPLs & Debugger: python, node, irb, gdb/lldb

• Texteditoren: vim, nano, emacs -nw

MCP-Konfiguration

Claude Code (CLI)

claude mcp add interactive-shell node /path/to/interactive-shell-mcp/dist/src/server.js

Claude Desktop

Hinzufügen zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "interactive-shell": {
      "command": "node",
      "args": ["/path/to/interactive-shell-mcp/dist/src/server.js"]
    }
  }
}

VS Code / Cursor

Hinzufügen zu Ihren MCP-Einstellungen (.vscode/mcp.json oder ~/.cursor/mcp.json):

{
  "mcpServers": {
    "interactive-shell": {
      "command": "node",
      "args": ["/path/to/interactive-shell-mcp/dist/src/server.js"]
    }
  }
}

Tools-Referenz

start_shell_session

Startet eine neue PTY-Shell mit einem virtuellen Terminal-Emulator.

Gibt { sessionId, cols, rows } zurück

send_shell_input

Schreibt Eingaben in das PTY. Hängt standardmäßig einen Wagenrücklauf (Carriage Return) an.

read_shell_output

Liest die Ausgabe vom PTY. Drei Modi: streaming (Standard), snapshot, screen.

Der Screen-Modus gibt die Cursorposition, Terminalabmessungen und den Status des alternativen Puffers in den Metadaten zurück.

get_screen_region

Extrahiert Text aus einem rechteckigen Bereich des Bildschirms.

get_screen_cursor

Ruft die Cursorposition und den Text der aktuellen Zeile ab.

Gibt { cursor: { x, y }, currentLine, isAlternateBuffer } zurück

search_screen

Durchsucht den Terminalbildschirm nach Text oder Regex. Gibt bis zu 50 Treffer zurück.

Gibt { results: [{ row, col, text }], count } zurück

list_sessions

Listet alle aktiven Sitzungen mit Metadaten auf. Keine Parameter.

Gibt { sessions: [{ sessionId, shell, cols, rows, isAlternateBuffer, idleSeconds }] } zurück

resize_shell

Ändert die Größe des Terminals einer aktiven Sitzung.

end_shell_session

Schließt das PTY und bereinigt Ressourcen.

Nutzungsbeispiele

Diese zeigen die MCP-Tool-Aufrufmuster für Entwickler, die Integrationen erstellen. Endbenutzer kommunizieren einfach natürlich mit ihrem KI-Agenten.

Lesen einer TUI-App

await send_shell_input(sessionId, "htop");
const { output, metadata } = await read_shell_output(sessionId, {
  mode: "screen",
  waitForIdle: 500
});
// output: rendered htop as clean text (CPU bars, process table, etc.)
// metadata.isAlternateBuffer: true (htop uses alternate screen)

// Extract just the process list (rows 6-30)
const processes = await get_screen_region(sessionId, {
  startRow: 6, startCol: 0, endRow: 30, endCol: 120,
  trimWhitespace: true
});

Navigieren durch interaktive Prompts

// Send arrow keys and enter in raw mode
await send_shell_input(sessionId, "\\x1b[B", { raw: true });  // down arrow
await send_shell_input(sessionId, " ", { raw: true });         // space to select
await send_shell_input(sessionId, "\\r", { raw: true });       // enter to confirm

// Read what the prompt looks like now
const screen = await read_shell_output(sessionId, {
  mode: "screen", waitForIdle: 300
});

Warten auf Befehlsausgabe

await send_shell_input(sessionId, "npm install");
const output = await read_shell_output(sessionId, {
  waitForIdle: 1000  // wait for 1s of silence
});

Suchen nach Inhalten

// Find all error lines
const errors = await search_screen(sessionId, {
  pattern: "error|Error|ERROR",
  regex: true,
  waitForIdle: 500
});
// [{ row: 12, col: 0, text: "Error" }, ...]

Sitzungsverhalten

• Automatische Bereinigung: Sitzungen, die länger als 10 Minuten im Leerlauf sind, werden automatisch verworfen

• Exit-Erkennung: Wenn eine Shell beendet wird, geben Tools für 60 Sekunden "Session exited with code N" zurück, anstatt eines generischen Fehlers für eine ungültige ID

• Shell-Allowlist: Nur bekannte Shells können gestartet werden (bash, zsh, fish, sh, dash, ksh, powershell.exe, pwsh, cmd.exe). Unbekannte Werte fallen auf den Plattform-Standard zurück.

Lizenz

MIT