# Interactive Terminal MCP
**English** | [中文](README_zh-CN.md)
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.<br><br>> `ssh user@host "cd /var/www"` (exits)<br>> `ssh user@host "ls"` (starts in home dir) | **Context Preserved**: Maintains one connection.<br><br>1. `spawn_process(["ssh", "user@host"])`<br>2. `send_command(id, "cd /var/www")`<br>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.<br><br>1. `spawn_process(["gdb", "./binary"])`<br>2. `send_command(id, "break main")`<br>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
```bash
uvx interactive-terminal-mcp
```
### Integration with Claude Code
You can add this server to Claude Code `uvx`.
**Using pipx:**
```bash
claude mcp add --transport stdio interactive-terminal-mcp -- uvx interactive-terminal-mcp
```
**Manual Configuration (`claude_config.json`):**
```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](https://asciinema.org/)) 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.
