mcp-interactive-terminal

MCP server that gives AI agents (Claude Code, Cursor, Windsurf, etc.) real interactive terminal sessions. Run REPLs, SSH, database clients, and any interactive CLI — with clean text output, smart completion detection, and 7-layer security.
Why This Exists
AI coding agents can't handle interactive commands. There's no PTY, no stdin streaming. You can't run rails console, python, psql, ssh, or any REPL through them. This MCP server fixes that.
Install
Claude Code
That's it. The server is now available. Ask Claude to "open a python REPL and calculate 2**100".
Cursor
Go to **Settings > MCP Servers**, click **Add Server**, and enter:
Windsurf
Add to your MCP configuration:
VS Code (GitHub Copilot)
Add to your .vscode/mcp.json:
Any MCP Client
The server communicates over stdio using the Model Context Protocol. Any MCP-compatible client can use it with the same npx -y mcp-interactive-terminal command.
Real-World Examples
Rails Console
Python REPL
Database Client
SSH
Docker
Node.js REPL
Tools
The server exposes 7 MCP tools:
create_session — Spawn an interactive process
| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| command | Yes | — | Command to run (bash, python3, psql, ssh, etc.) |
| args | No | [] | Command arguments |
| name | No | auto | Human-readable session name |
| cwd | No | server cwd | Working directory |
| env | No | {} | Additional environment variables |
| cols | No | 120 | Terminal columns |
| rows | No | 40 | Terminal rows |
send_command — Send input and get output
| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| session_id | Yes | — | Target session |
| input | Yes | — | Command/input to send (newline appended automatically) |
| timeout_ms | No | 5000 | Max wait time for output |
| max_output_chars | No | 20000 | Truncate output beyond this |
Dangerous commands (rm -rf, DROP TABLE, curl|bash, etc.) are blocked — the agent must use confirm_dangerous_command first.
read_output — Read terminal screen (read-only)
Safe to auto-approve — this only reads, never sends input.
list_sessions — List active sessions (read-only)
Safe to auto-approve.
close_session — Kill a session
send_control — Send control characters
Supported: ctrl+c, ctrl+d, ctrl+z, ctrl+l, ctrl+r, tab, escape, up, down, left, right, enter, backspace, delete, home, end, and more.
confirm_dangerous_command — Two-step safety confirmation
Required when send_command detects a dangerous pattern. The agent must explain why the command is necessary. This is a **separate tool** — even if send_command is auto-approved, this requires its own permission.
How It Works
Two Terminal Modes
**PTY mode** (default) — uses node-pty + @xterm/headless (the same terminal emulator as VS Code):
- Clean output — the AI sees exactly what a human would see on screen
- Cursor positioning, progress bars, \r overwrites all render correctly
- Full keyboard: arrow keys, tab completion, ctrl+c/d/z, home/end
- Terminal resize, TUI apps (vim, htop, top), 256-color, 1000-line scrollback
**Pipe mode** (automatic fallback) — activates when node-pty can't load (e.g., in sandboxed environments):
- Interactive sessions still work via child_process.spawn with auto-injected flags (python -u -i, bash -i, etc.)
- ANSI codes stripped, control keys still work
- No terminal emulation, but covers the basics
The mode is selected automatically — PTY is tried first, pipe mode kicks in if it fails.
What the AI sees: PTY vs Pipe
| Scenario | PTY mode | Pipe mode |
|----------|----------|-----------|
| printf "\rProgress: 3/3" | Progress: 3/3 | Progress: 1/3Progress: 2/3Progress: 3/3 |