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.

AI Agent (Claude Code, Cursor, etc.)
    ↕  MCP (JSON-RPC over stdio)
mcp-interactive-terminal
    ↕  node-pty + xterm-headless
Interactive Process (rails console, python, psql, ssh, bash...)
    ↕
Clean text output (exactly what a human would see)

Install

Claude Code

claude mcp add terminal -- npx -y mcp-interactive-terminal

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:

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-terminal"]
    }
  }
}

Windsurf

Add to your MCP configuration:

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-terminal"]
    }
  }
}

VS Code (GitHub Copilot)

Add to your .vscode/mcp.json:

{
  "servers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-terminal"]
    }
  }
}

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

You: "Open rails console for staging and check the user count"

Agent creates session → bash
Agent sends: cd /path/to/app && rails console -e staging
Agent sends: User.count
Agent returns: 1,847,293

Python REPL

You: "Open python and test my sorting algorithm"

Agent creates session → python3
Agent sends: def quicksort(arr): ...
Agent sends: quicksort([3, 1, 4, 1, 5, 9])
Agent returns: [1, 1, 3, 4, 5, 9]

Database Client

You: "Connect to postgres and show me the largest tables"

Agent creates session → psql -U myuser mydb
Agent sends: SELECT tablename, pg_size_pretty(pg_total_relation_size(tablename::text)) ...
Agent returns: formatted table of results

SSH

You: "SSH into the staging server and check disk usage"

Agent creates session → ssh user@staging.example.com
Agent sends: df -h
Agent returns: disk usage table

Docker

You: "Open a shell in my running container and check the logs"

Agent creates session → docker exec -it my-container bash
Agent sends: tail -100 /var/log/app.log
Agent returns: last 100 log lines

Node.js REPL

You: "Open node and test the date parsing logic"

Agent creates session → node
Agent sends: new Date('2024-02-29').toISOString()
Agent returns: 2024-02-29T00:00:00.000Z

Tools

The server exposes 7 MCP tools:

create_session — Spawn an interactive process

{ "command": "python3", "name": "my-python", "cwd": "/project" }
→ { "session_id": "a1b2c3d4", "name": "my-python", "pid": 12345 }

send_command — Send input and get output

{ "session_id": "a1b2c3d4", "input": "1 + 1" }
→ { "output": "2", "is_complete": true, "is_alive": true }

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)

{ "session_id": "a1b2c3d4" }
→ { "output": ">>> ", "is_alive": true }

Safe to auto-approve — this only reads, never sends input.

list_sessions — List active sessions (read-only)

→ [{ "session_id": "a1b2c3d4", "name": "my-python", "command": "python3", "pid": 12345, "is_alive": true }]

Safe to auto-approve.

close_session — Kill a session

{ "session_id": "a1b2c3d4" }
→ { "success": true }

send_control — Send control characters

{ "session_id": "a1b2c3d4", "control": "ctrl+c" }
→ { "output": "^C\n>>>" }

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

{ "session_id": "a1b2c3d4", "input": "rm -rf /tmp/old", "justification": "Cleaning up stale temp files from failed build" }
→ { "output": "...", "is_complete": true, "is_alive": true }

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

Smart "Command Done" Detection

Instead of blindly waiting a fixed time, the server uses a layered strategy:

1. Process exit — if the process died, command is done
2. Prompt detection — auto-detects the session's prompt at startup (bash $, python >>>, psql #, etc.), watches for it to reappear
3. Output settling — no new output for 300ms = probably done
4. Timeout — always returns after timeout_ms with is_complete: false

Security

Seven-layer defense-in-depth:

Recommended Permissions

Only auto-approve the read-only tools:

{
  "permissions": {
    "allow": [
      "mcp__terminal__list_sessions",
      "mcp__terminal__read_output"
    ]
  }
}

This way send_command, create_session, and especially confirm_dangerous_command always require human approval.

Configuration

All settings via environment variables. Pass them in your MCP config:

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-terminal"],
      "env": {
        "MCP_TERMINAL_ALLOWED_COMMANDS": "bash,python3,node,psql",
        "MCP_TERMINAL_REDACT_SECRETS": "true",
        "MCP_TERMINAL_IDLE_TIMEOUT": "300000"
      }
    }
  }
}