Interactive Shell MCP

MCP server for interactive shell sessions with TUI support. Gives AI agents persistent terminals, interactive prompt navigation, rendered screen reading, and output search.

Demo

Why This Exists

Most AI coding tools run shell commands in isolation: each command starts a fresh shell, interactive prompts are impossible, and TUI apps just dump raw escape codes. This MCP server provides persistent PTY sessions with a virtual terminal emulator (@xterm/headless) so agents can maintain shell state, navigate interactive prompts with arrow keys, and read rendered terminal screens as clean text.

Three output modes:

Quick Start

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

Then ask Claude: "monitor htop and tell me what's using the most CPU"

Features

• Rendered screen reading from TUI apps via @xterm/headless

• waitForIdle across all read tools (no more guessing with sleep)

• Screen search with text and regex pattern matching

• Rectangular region extraction with row/col coordinates

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

• Auto-cleanup after 10min idle, exit code detection for 60s after process exit

• Cross-platform: Unix/Linux/macOS + Windows

Use Cases

• Interactive scaffolding & migrations: npx create-next-app, drizzle-kit push, prisma migrate, npm init, or any inquirer/clack-based CLI

• System monitoring: htop, btop, top, iftop, duf with process search and region extraction

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

• Remote sessions: ssh into servers, including nested TUI apps over SSH

• Database CLIs: psql, mysql, redis-cli, mongosh in interactive mode

• Network tools: netcat/ncat, nmap, airodump-ng, tcpdump

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

• Text editors: vim, nano, emacs -nw

MCP Configuration

Claude Code (CLI)

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

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %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

Add to your MCP settings (.vscode/mcp.json or ~/.cursor/mcp.json):

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

Tools Reference

start_shell_session

Spawn a new PTY shell with a virtual terminal emulator.

Returns { sessionId, cols, rows }

send_shell_input

Write input to the PTY. Appends carriage return by default.

read_shell_output

Read output from the PTY. Three modes: streaming (default), snapshot, screen.

Screen mode returns cursor position, terminal dimensions, and alternate buffer state in metadata.

get_screen_region

Extract text from a rectangular region of the screen.

get_screen_cursor

Get cursor position and current line text.

Returns { cursor: { x, y }, currentLine, isAlternateBuffer }

search_screen

Search the terminal screen for text or regex. Returns up to 50 matches.

Returns { results: [{ row, col, text }], count }

list_sessions

List all active sessions with metadata. No parameters.

Returns { sessions: [{ sessionId, shell, cols, rows, isAlternateBuffer, idleSeconds }] }

resize_shell

Resize an active session's terminal.

end_shell_session

Close the PTY and clean up resources.

Usage Examples

These show the MCP tool call patterns for developers building integrations. End users just talk to their AI agent naturally.

Reading a 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
});

Navigating Interactive 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
});

Waiting for Command Output

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

Searching for Content

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

Session Behavior

• Auto-cleanup: Sessions idle >10 minutes are disposed automatically

• Exit detection: When a shell exits, tools return "Session exited with code N" for 60 seconds instead of a generic invalid ID error

• Shell allowlist: Only known shells can be spawned (bash, zsh, fish, sh, dash, ksh, powershell.exe, pwsh, cmd.exe). Unknown values fall back to platform default.

License

MIT