# interactive-terminal

Gives an AI agent a real interactive shell session: REPLs, SSH, psql, docker exec. PTY emulation plus a guard on dangerous commands.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 19
- Author: amol21p
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/amol21p/mcp-interactive-terminal
- Updated: 2026-02-16
- HTML: https://affpapa.org/en/nevibecode/mcp/interactive-terminal

## What it does

Coding agents like Claude and Cursor stall on interactive programs. No PTY, no streaming input, so `rails console`, `psql` or `ssh` never get past the prompt. This server spawns the process itself and hands the agent plain screen text, matching what a person would read.

Seven tools cover the loop. `create_session` starts a process, `send_command` writes a line and waits for output, `read_output` and `list_sessions` are read-only, `close_session` shuts it down, `send_control` fires keys like `ctrl+c` or `tab`. Risky input such as `rm -rf` or `DROP TABLE` gets stopped at `send_command`, and the agent has to go through `confirm_dangerous_command` with a stated reason. That second tool carries its own permission, so auto-approving sends does not let a destructive command slip through.

Under the hood sit `node-pty` and `@xterm/headless`, which is why arrow keys, progress bars and TUI apps like vim or htop render properly. When `node-pty` fails to load, the server falls back to `child_process.spawn` with injected flags such as `python -u -i`; sessions still run, just without terminal emulation. Node.js 18 or newer is required. Keep in mind this is real shell access on your machine, so set the session cap and sandbox through the environment variables from the start.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `MCP_TERMINAL_MAX_SESSIONS`, `MCP_TERMINAL_SANDBOX`, `MCP_TERMINAL_REDACT_SECRETS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env MCP_TERMINAL_MAX_SESSIONS=<MCP_TERMINAL_MAX_SESSIONS> --env MCP_TERMINAL_SANDBOX=<MCP_TERMINAL_SANDBOX> --env MCP_TERMINAL_REDACT_SECRETS=<MCP_TERMINAL_REDACT_SECRETS> --transport stdio interactive-terminal -- npx -y mcp-interactive-terminal
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add interactive-terminal --env MCP_TERMINAL_MAX_SESSIONS=<MCP_TERMINAL_MAX_SESSIONS> --env MCP_TERMINAL_SANDBOX=<MCP_TERMINAL_SANDBOX> --env MCP_TERMINAL_REDACT_SECRETS=<MCP_TERMINAL_REDACT_SECRETS> -- npx -y mcp-interactive-terminal
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "interactive-terminal": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-interactive-terminal"
            ],
            "env": {
                "MCP_TERMINAL_MAX_SESSIONS": "<MCP_TERMINAL_MAX_SESSIONS>",
                "MCP_TERMINAL_SANDBOX": "<MCP_TERMINAL_SANDBOX>",
                "MCP_TERMINAL_REDACT_SECRETS": "<MCP_TERMINAL_REDACT_SECRETS>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "interactive-terminal": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "mcp-interactive-terminal"
            ],
            "env": {
                "MCP_TERMINAL_MAX_SESSIONS": "<MCP_TERMINAL_MAX_SESSIONS>",
                "MCP_TERMINAL_SANDBOX": "<MCP_TERMINAL_SANDBOX>",
                "MCP_TERMINAL_REDACT_SECRETS": "<MCP_TERMINAL_REDACT_SECRETS>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e MCP_TERMINAL_MAX_SESSIONS=<MCP_TERMINAL_MAX_SESSIONS> -e MCP_TERMINAL_SANDBOX=<MCP_TERMINAL_SANDBOX> -e MCP_TERMINAL_REDACT_SECRETS=<MCP_TERMINAL_REDACT_SECRETS> interactive-terminal npx -y mcp-interactive-terminal
```
Replace <…> with your own values

## When to use it
- query the staging user count from `rails console`
- list the biggest tables in a postgres database
- check disk usage over SSH on a remote host
- tail an app log inside a running container
- test a sorting function in a live python REPL

## Example prompts
- Open python and run my sorting function on a sample list.
- Get a shell in `my-container` and read the last lines of the log.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md