home / mcp / mcp interactive terminal mcp server

MCP Interactive Terminal MCP Server

Provides an interactive terminal server for AI agents to run REPLs, SSH, databases, and other interactive CLIs with clean output and multi-layer security.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "amol21p-mcp-interactive-terminal": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-interactive-terminal"
      ],
      "env": {
        "MCP_TERMINAL_SANDBOX": "false",
        "MCP_TERMINAL_AUDIT_LOG": "/var/log/mcp-audit.json",
        "MCP_TERMINAL_LOG_INPUTS": "false",
        "MCP_TERMINAL_MAX_OUTPUT": "20000",
        "MCP_TERMINAL_IDLE_TIMEOUT": "300000",
        "MCP_TERMINAL_MAX_SESSIONS": "10",
        "MCP_TERMINAL_ALLOWED_PATHS": "/home,/workspace",
        "MCP_TERMINAL_REDACT_SECRETS": "true",
        "MCP_TERMINAL_DEFAULT_TIMEOUT": "5000",
        "MCP_TERMINAL_ALLOWED_COMMANDS": "bash,python3,node,psql",
        "MCP_TERMINAL_BLOCKED_COMMANDS": "rm -rf,DROP TABLE",
        "MCP_TERMINAL_DANGER_DETECTION": "true",
        "MCP_TERMINAL_SANDBOX_ALLOW_WRITE": "/tmp",
        "MCP_TERMINAL_SANDBOX_ALLOW_NETWORK": "*"
      }
    }
  }
}

You can run AI agents against interactive shell tools, REPLs, databases, SSH, and other CLI applications through a dedicated MCP server that preserves human-like terminal behavior. This server provides clean text output, smart completion detection, and strong security, enabling AI agents to interact with real interactive processes as if a human were typing.

How to use

Connect any MCP client to the server using the standard MPC workflow. You start a session to run an interactive process, send commands, and read outputs just as you would in a normal terminal. The server handles the complexity of terminal emulation behind a simple, consistent API, so you can open a Python REPL, run a Rails console, access a PostgreSQL prompt, SSH into a host, or interact with any interactive CLI.

How to install

Prerequisites: Node.js version 18 or newer. Ensure you have an MCP client ready to connect via stdio.

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

Configuration and usage notes

This MCP server exposes a single stdio-based server that you can run locally or in your environment. The server command and arguments shown here must be used exactly as written to start the MCP server for interactive terminal sessions.

Security and safeguards

Security is built in with seven layers of protection, including confirmation flows for dangerous commands, input pattern detection, OS-level sandboxing options, secret redaction, and strict auditing controls. You can configure these protections to suit your environment and risk posture.

Examples of real-world use

Open a Python REPL, inspect a Rails console, connect to PostgreSQL, or SSH into a remote server. The agent creates a session, the server runs the requested interactive command, and you receive clean, human-readable output with the ability to send further input or control commands.

Troubleshooting

If the terminal output looks garbled or you encounter an environment where PTY is unavailable, the server automatically falls back to a pipe mode that still supports interactive commands. Install required build tools to enable full PTY support where possible.

Notes on performance and behavior

The server detects when a command is finished by process exit, prompt appearance, output settlement, or a timeout. This helps determine when the agent can proceed with the next step without unnecessary waiting.

Development and testing

Set up the repository, install dependencies, build, and run tests locally to verify interactive sessions work as expected.

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

Available tools

create_session

Spawn an interactive process with a given command, arguments, and environment to start an interactive session.

send_command

Send input to the active session and receive output, with optional timeout and output truncation.

read_output

Read the current terminal screen without sending input to the process.

list_sessions

List all active interactive sessions with basic metadata.

close_session

Terminate a running interactive session.

send_control

Send control characters such as ctrl+c, ctrl+d, arrow keys, and other keys to the session.

confirm_dangerous_command

Request explicit justification for dangerous commands before execution.