Skip to main content
Glama

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.

Related MCP server: Terminal MCP

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

Available Tools

6 tools
connect_sshA
Opens a persistent SSH connection and returns a session_id for use with
`execute`. The connection stays open until `disconnect`. Host keys are
auto-accepted. For local commands, call `execute` directly — no session needed.

PARAMETER GUIDANCE: Reuse session_id across multiple execute calls —
each connect_ssh opens a new TCP connection. key_filepath is tried
first when both key and password are provided; password acts as
fallback. With neither, SSH agent and system defaults are used. The
username defaults to the OS user if omitted. host is resolved at
connect time; unresolvable names raise an error. banner_timeout
controls MOTD capture — if exceeded, banner returns "" (not an error);
set to 0 to skip capture entirely.

SIDE EFFECTS: Opens a TCP socket with a 30-second keepalive. Leaks
the socket if `disconnect` is never called.

ERRORS: Raises on auth failure, unresolvable host, refused connection,
or network timeout.

RETURNS: {"session_id": str, "banner": str}

Inputs: host (required), port, password, username, +2 more.

disconnectA
DestructiveIdempotent
Close an SSH session and release all associated resources. NOT needed
for local commands — those clean up automatically.

SESSION_ID LIFECYCLE: The id is an opaque UUID created by connect_ssh,
used with execute, and retired by this call. Each connect_ssh produces
a unique id — reconnecting the same host gives a new one. After
disconnect, execute() with the old id raises ValueError. Calling
disconnect on an already-closed or unknown id is a safe no-op
(idempotent), so cleanup logic never needs to guard against double-close.

SIDE EFFECTS: Terminates all running commands on this session (their
command_ids become invalid), closes SSH channels and TCP socket.

WHEN NOT TO USE: To stop a single command without closing the session,
use send_control with "ctrl+c" instead.

RETURNS: true (always succeeds).

Inputs: session_id (required). Returns: result

executeA
Destructive
Execute a command locally or over SSH in an isolated channel.

PARAMETER RELATIONSHIPS & VALIDATION:
- `session_id` vs `shell`: `session_id` determines the execution environment. If provided (must be a valid active session), it runs over SSH and `shell` is completely ignored. If omitted, it runs locally, and `shell` (e.g., 'powershell.exe', '/bin/bash') is used.
- `pause_timeout` vs `total_timeout`: These interact to manage execution time. `pause_timeout` (must be > 0) triggers an early return if the command goes silent for that many seconds. `total_timeout` (must be >= `pause_timeout`) sets a hard wall-clock limit even if output is constantly streaming. To wait longer for a quiet command (e.g., a build), increase `pause_timeout`.
- Both timeouts accept floats but invalid ranges (e.g., pause_timeout <= 0, or total_timeout < pause_timeout) or an unknown `session_id` will raise a ValueError.

WHEN NOT TO USE: 
Do not use this to send input to an existing command (`respond`), send control keys (`send_control`), or poll a running command (`read_output`).

SIDE EFFECTS: 
Spawns a new, stateless process. `cd` or environment variables do NOT persist between calls. For persistent state, start a terminal multiplexer in the foreground. Never use `&` to background TUI apps.

RETURNS:
- {"status": "completed", "output": str, "exit_code": int}
- {"status": "partial", "output": str, "command_id": str}

Inputs: command (required), shell, session_id, pause_timeout, +1 more.

read_outputA
Read-only
Poll new output from a running command without sending input. Use after
execute returns status="partial" for non-interactive commands (builds,
training loops, long searches).

Each call returns only output produced since the last read. When the
command finishes, status changes to "completed" and the command_id is
retired — further calls raise ValueError.

WHEN NOT TO USE: If the command expects input, use respond. If you
need to interrupt or send keys, use send_control.

PARAMETER GUIDANCE: pause_timeout is the primary dial — it controls
how long to wait when the command is silent. total_timeout only caps
actively streaming output and has no effect during silence.

ERRORS: Raises ValueError if command_id is invalid or already completed.

RETURNS:
- {"status": "partial", "output": str, "command_id": str}
- {"status": "completed", "output": str, "exit_code": int}

Inputs: command_id (required), pause_timeout, total_timeout.

respondA
Destructive
Write text to a running command's stdin. Works for prompts (y/n,
passwords), shell input, or any text the process expects.

PARAMETER GUIDANCE: text auto-appends \n if missing. For control
keys use send_control — AI frameworks strip control bytes. Raise
pause_timeout (not total_timeout) for slow responses after input.
Raises ValueError if command_id is invalid or completed.

WHEN NOT TO USE: Inside zellij, prefer multiplexer CLI via execute.

SIDE EFFECTS: Writes to stdin; may trigger output, state change, or exit.

RETURNS:
- {"status": "partial", "output": str, "command_id": str}
- {"status": "completed", "output": str, "exit_code": int}

Inputs: text (required), command_id (required), pause_timeout, total_timeout.

send_controlA
Destructive
Send a control key or escape sequence to a running command. Use for
interrupts (ctrl+c), TUI navigation (arrows, F-keys), or any
non-printable input. Prefer this over `respond` for control keys —
AI frameworks strip raw control bytes from string arguments.

SIGNAL HANDLING: The signal parameter accepts any key name from the
supported list (case-insensitive, whitespace-tolerant — "Ctrl + C"
works). Common signals: ctrl+c (SIGINT/interrupt), ctrl+z (SIGTSTP/
suspend), ctrl+d (EOF), ctrl+\ (SIGQUIT). Local non-PTY subprocesses
only react to ctrl+c, ctrl+z, ctrl+\; SSH and PTY channels accept all.

SIDE EFFECTS: The signal may terminate the command (e.g. ctrl+c),
making the command_id invalid on the next read.

TIMEOUT INTERACTION: pause_timeout controls how long to wait for
output after the signal. Raise it for slow TUI repaints over
high-latency SSH; total_timeout only binds during active streaming.

ERRORS: Raises ValueError if command_id is invalid, already completed,
or signal name is unrecognized.

RETURNS: Same format as execute —
{"status": "completed"|"partial", "output": str, ...}

Inputs: signal (required), command_id (required), pause_timeout, total_timeout.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.9/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct action in the terminal/SSH lifecycle: connect_ssh establishes sessions, execute runs commands, respond sends text input, read_output polls output, send_control handles control keys, and disconnect tears down sessions. Descriptions clearly delimit text vs control input and initiating vs polling execution, so an agent can reliably select the right tool.

    Naming Consistency4/5

    Names mostly follow a predictable imperative snake_case pattern, with verb_noun forms like connect_ssh, read_output, and send_control. The bare verbs execute, respond, and disconnect are a minor deviation but do not create confusion; the overall style is consistent and readable.

    Tool Count5/5

    Six tools form a well-scoped set for terminal and SSH management: connect, execute, interact, read, control, and disconnect. No tool is redundant, and the count is neither too thin nor bloated for the server's purpose.

    Completeness5/5

    The tool set covers the full command lifecycle: opening and closing sessions, running commands locally or remotely, sending text input, sending control keys, and polling output. There are no obvious dead ends—session IDs and command IDs are consistently managed across the available operations.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      A secure and pluggable MCP server to run terminal commands on your local machine or cloud server — remotely, safely, and with LLMs or agentic clients.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables management of visible, interactive terminal sessions across platforms (macOS, Windows, Linux, WSL). Supports creating, executing commands, capturing output, and managing multiple terminal windows simultaneously.
      5
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that enables AI agents to run fully interactive SSH sessions (via tmux) and execute commands like a human operator, with persistent sessions and multiple concurrent connections.
      6
      MIT