interactive-terminal-mcp 0.1.4

Add your description here

Interactive Terminal MCP

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.