interminal
This server gives AI assistants terminal access to both local and remote SSH environments, supporting interactive and long-running commands.
Connect to SSH servers (
connect_ssh): Establish persistent SSH sessions with password or key-based authentication, receiving asession_idfor subsequent commands.Create local shell sessions (
create_local): Spawn a persistent local shell (bash, zsh, PowerShell, etc.) on the host machine with full execution privileges.Execute commands (
execute): Run shell commands in any active session; short commands return output immediately (status=completed), while long-running commands returnstatus=partialwith acommand_idfor further interaction.Poll running command output (
read_output): Retrieve new output from a still-running command without sending input — useful for monitoring builds or background processes.Respond to interactive prompts (
respond): Send text input (e.g., answering[Y/n]prompts or entering passwords) to a command waiting for user input.Send control keys and signals (
send_control): Transmit control characters and key sequences (Ctrl+C, arrow keys, F-keys, ESC, Tab, etc.) to interrupt commands or drive TUI applications like vim, htop, or Zellij.List active sessions (
list_sessions): View all currently open SSH and local sessions, including their type and connection details.Disconnect sessions (
disconnect): Gracefully close a session, terminating all associated processes and freeing resources.Configure command timeouts: Control response timing using
pause_timeout(output silence) andtotal_timeout(hard duration limits).
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-interminalRequires 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 to an SSH server; returns |
| Run a command locally (no session needed) or over SSH; returns output or |
| Poll a running command for new output without sending input |
| Send text input to a command waiting at a prompt |
| Send control keys: |
| 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 /foodoes not persist. Simple tasks: chain with&&. Multi-step workflows: use a terminal multiplexer.Long-running commands return
status="partial"with acommand_id; poll withread_outputor send input withrespondSSH 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]" # bothAvailable Tools
6 toolsconnect_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.
disconnectADestructiveIdempotent
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
executeADestructive
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_outputARead-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.
respondADestructive
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_controlADestructive
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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
SSH client, server management and one remote MCP URL for your machines, with human approvals.
Termalin's hosted MCP server. Claude, ChatGPT or any MCP client runs commands, moves files over SFTP, queries databases and reads server metrics and monitoring alerts on your servers, keylessly through Termalin Connectors: no SSH key is handed over and no inbound port is opened. Per-host command policy and an audit log. Needs a termal.in Pro or Team account (new accounts start with a 14-day Pro trial).
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceA secure and pluggable MCP server to run terminal commands on your local machine or cloud server — remotely, safely, and with LLMs or agentic clients.-
- AlicenseAqualityDmaintenanceEnables management of visible, interactive terminal sessions across platforms (macOS, Windows, Linux, WSL). Supports creating, executing commands, capturing output, and managing multiple terminal windows simultaneously.51MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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.6MIT
- AlicenseBqualityDmaintenanceLocal + remote terminal interaction control MCP Server. Lets AI agents control interactive TUI programs the way a human would.297 npmMIT