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"
      }
    }
  }
}

Troubleshooting

"Tools not showing up" / Server fails silently

MCP servers that fail to start often show no error in the client. Check:

# Test the server directly:
npx -y mcp-interactive-terminal

# You should see "[mcp-terminal] Starting MCP Interactive Terminal Server" on stderr.
# If you see an error, that's what's failing.

Node.js version too old

The server requires Node.js >= 18. If you see errors about unsupported syntax or missing APIs:

node --version  # Must be >= 18

# If using nvm:
nvm install 18 && nvm use 18

# If using volta:
volta install node@18

For nvm/volta/fnm users: npx may use a different Node version than your shell. Use an absolute path:

{
  "mcpServers": {
    "terminal": {
      "command": "/Users/you/.nvm/versions/node/v22.0.0/bin/npx",
      "args": ["-y", "mcp-interactive-terminal"]
    }
  }
}

Find your path with: which npx

node-pty compilation errors

node-pty is a native module that requires build tools. If it fails to compile, the server automatically falls back to pipe mode — interactive sessions still work, just without terminal emulation.

If you want full PTY support:

# macOS:
xcode-select --install

# Ubuntu/Debian:
sudo apt-get install -y make python3 build-essential

# RHEL/Fedora:
sudo yum install -y make python3 gcc gcc-c++

Session dies immediately

Some commands need to be run inside a shell rather than directly:

# Instead of:  create_session({ command: "rails console -e staging" })
# Do this:     create_session({ command: "bash" })
#              send_command({ input: "rails console -e staging" })

This is because create_session runs the command directly (like exec), not through a shell. Spawning bash first gives you a full shell environment.

Output looks garbled

If output contains escape codes or looks wrong, you're likely in pipe mode (node-pty failed to load). Check the server logs for "falling back to pipe mode". Install build tools (see above) to enable PTY mode.

Timeout too short for long-running commands

Increase the timeout per-command:

{ "session_id": "...", "input": "bundle install", "timeout_ms": 60000 }

Or globally via environment variable:

{ "env": { "MCP_TERMINAL_DEFAULT_TIMEOUT": "30000" } }

Comparison with Alternatives

Development

git clone https://github.com/amol21p/mcp-interactive-terminal.git
cd mcp-interactive-terminal
npm install
npm run build
npm test

Test with MCP Inspector:

npx @modelcontextprotocol/inspector dist/index.js

License

MIT