interactive-terminal — Claude Code MCP server
Gives an AI agent a real interactive shell session: REPLs, SSH, psql, docker exec. PTY emulation plus a guard on dangerous commands.
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-terminalWhat interactive-terminal 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.
What it helps with
- 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 for the agent
- Open python and run my sorting function on a sample list.
- Get a shell in
my-containerand read the last lines of the log.
How to install interactive-terminal
Platform CLI
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-terminalReplace <…> with your own values
Platform CLI
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-terminalReplace <…> with your own values
Config file
{
"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
Config file
{
"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
Platform CLI
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-terminalReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about interactive-terminal
How do I install interactive-terminal in Claude Code?
Run claude mcp add interactive-terminal -- npx -y mcp-interactive-terminal. The server is then available to the agent.
What does interactive-terminal do?
It keeps interactive processes alive — REPLs, SSH sessions, database clients, shells — and returns readable terminal output to the agent. Without it, those sessions die at the prompt.
What do I need to run it?
Node.js 18 or newer. It speaks MCP over stdio, so any compatible client can launch it with npx -y mcp-interactive-terminal.
