Interminal

Lightweight MCP server that gives AI assistants terminal access — SSH and local shells — with support for interactive and long-running commands.

Installation

# Run directly, no install needed (recommended)
uvx mcp-interminal

# Or install permanently
pip install mcp-interminal

Requires Python ≥ 3.11.

MCP Client Configuration

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "interminal": {
      "command": "uvx",
      "args": ["mcp-interminal"]
    }
  }
}

Cursor / other clients: same command + args format above.

Tools

Tool	Description
`connect_ssh`	Connect to an SSH server; returns `session_id` and welcome banner
`execute`	Run a command locally (no session needed) or over SSH; returns output or `status=partial` + `command_id`
`read_output`	Poll a running command for new output without sending input
`respond`	Send text input to a command waiting at a prompt
`send_control`	Send control keys: `ctrl+c`, `ctrl+z`, arrow keys, F-keys, etc.
`disconnect`	Close an SSH session and release all resources

Persistent State

Each execute call runs in an isolated channel — there is no persistent shell between calls. For simple tasks, chaining with && works.

For multi-step workflows (project development, debugging, deployment), a terminal multiplexer (like Zellij) provides persistent state that survives across calls. The AI agent can create a persistent session where cd, environment variables, virtual environments, and long-running processes carry over naturally.

Key Behaviors

Stateless execute — each call is an isolated channel; cd /foo does not persist. Simple tasks: chain with &&. Multi-step workflows: use a terminal multiplexer.
Long-running commands return status="partial" with a command_id; poll with read_output or send input with respond
SSH PTY is 500×200 xterm-256color so multiplexer sessions render at your actual terminal size

Optional Dependencies

pip install "mcp-interminal[pty]"       # Windows PTY support (pywinpty)
pip install "mcp-interminal[ansi]"      # ANSI escape rendering (pyte)
pip install "mcp-interminal[pty,ansi]"  # both