Interactive Terminal MCP
English | 中文
A Model Context Protocol (MCP) server that provides stateful, interactive terminal access.
Unlike standard command execution tools that run in isolation, this server allows LLMs to spawn persistent processes (like ssh, ipython, or gdb), maintain session context, and interact with shells via standard input/output streams.
Why use this MCP?
Standard command execution tools usually run in isolation (stateless). This MCP server allows for persistent sessions (stateful), which is critical for remote management and debugging tools.
Side-by-Side Comparison
| Scenario | Without this MCP (Stateless) | With Interactive-Terminal-MCP (Stateful) |
|---|---|---|
| 1. Remote SSH Session | Context Lost: Must reconnect for every command. > ssh user@host "cd /var/www" (exits)> ssh user@host "ls" (starts in home dir) | Context Preserved: Maintains one connection. 1. spawn_process(["ssh", "user@host"])2. send_command(id, "cd /var/www")3. send_command(id, "ls") -> index.php |
| 2. Interactive Debugging | Unsupported: Cannot handle interactive prompts or wait for specific output patterns. | Supported: Can drive interactive tools. 1. spawn_process(["gdb", "./binary"])2. send_command(id, "break main")3. send_command(id, "run") |
Features
- Stateful Sessions: Environment variables, working directories, and process states persist between commands.
- Interactive Support: Specifically designed for REPLs and interactive CLIs that require continuous input.
- Output Control: Supports waiting for specific output patterns (regex) to ensure commands complete before returning.
- Session Management: Handle multiple concurrent terminal sessions.
- History: Access full session logs via MCP resources.
Usage
Running Directly
uvx interactive-terminal-mcp
Integration with Claude Code
You can add this server to Claude Code uvx.
Using pipx:
claude mcp add --transport stdio interactive-terminal-mcp -- uvx interactive-terminal-mcp
Manual Configuration (claude_config.json):
{
"mcpServers": {
"interactive-terminal": {
"command": "uvx",
"args": ["interactive-terminal-mcp"]
}
}
}
Available Tools
spawn_process
Starts a new interactive process.
- Arguments:
command(List[str]): The command to run (e.g.,["bash"],["python3", "-i"]).
- Returns:
session_id(str)
send_command
Sends input to an active session and waits for output.
- Arguments:
session_id(str): The target session ID.cmd(str): The command string to send.wait_for(str, optional): Regex pattern to wait for (e.g.,\$\s*). Defaults to a short timeout if not provided.timeout(int, optional): Maximum time to wait in seconds.
read_buffer
Reads any pending output from the session buffer without sending new commands.
- Arguments:
session_id(str)
kill_session
Terminates a specific session.
- Arguments:
session_id(str)
Resources
cli://{session_id}/history: Retrieves the full interaction history (inputs and outputs) for a specific session.
Roadmap
- Session Recording: Support saving interaction logs in standard formats (e.g., asciinema) for replay and auditing.
- Human Intervention: Enable mechanisms for users to pause, terminate, or manually intervene in active shell sessions managed by the Agent.
[!WARNING] Security Warning: This tool provides full terminal access to the connected LLM. The LLM will have the same permissions as the user running the MCP server. Use only in trusted environments or sandboxed containers (e.g., Docker) to prevent unauthorized system modifications.