# Interactive Terminal MCP
[English](README.md) | **中文**
一个 Model Context Protocol (MCP) 服务器，提供**有状态的、交互式的终端访问**。
与孤立运行的标准命令执行工具不同，该服务器允许 LLM 启动持久进程（如 `ssh`、`ipython` 或 `gdb`），维护会话上下文，并通过标准输入/输出流与 Shell 进行交互。
## 为什么要使用此 MCP？
标准命令执行工具通常是孤立运行的（无状态）。此 MCP 服务器支持持久会话（有状态），这对于远程管理和调试工具至关重要。
### 并排对比
| 场景 | 不使用此 MCP (无状态) | 使用 Interactive-Terminal-MCP (有状态) |
| :--- | :--- | :--- |
| **1. 远程 SSH 会话** | **上下文丢失**：必须为每个命令重新连接。<br><br>> `ssh user@host "cd /var/www"` (退出)<br>> `ssh user@host "ls"` (从主目录重新开始) | **上下文保留**：保持一个连接。<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. 交互式调试** | **不支持**：无法处理交互式提示或等待特定的输出模式。 | **支持**：可以驱动交互式工具。<br><br>1. `spawn_process(["gdb", "./binary"])`<br>2. `send_command(id, "break main")`<br>3. `send_command(id, "run")` |
## 特性
- **有状态会话**：环境变量、工作目录和进程状态在命令之间保持不变。
- **交互式支持**：专为需要连续输入的 REPL 和交互式 CLI 设计。
- **输出控制**：支持等待特定的输出模式（正则表达式），以确保命令在返回之前完成。
- **会话管理**：处理多个并发终端会话。
- **历史记录**：通过 MCP 资源访问完整的会话日志。
## 用法
### 直接运行
```bash
uvx interactive-terminal-mcp
```
### 与 Claude Code 集成
您可以将此服务器添加到 Claude Code `uvx`。
**使用 pipx:**
```bash
claude mcp add --transport stdio interactive-terminal-mcp -- uvx interactive-terminal-mcp
```
**手动配置 (`claude_config.json`):**
```json
{
"mcpServers": {
"interactive-terminal": {
"command": "uvx",
"args": ["interactive-terminal-mcp"]
}
}
}
```
## 可用工具
### `spawn_process`
启动一个新的交互式进程。
- **参数**:
- `command` (List[str]): 要运行的命令 (例如 `["bash"]`, `["python3", "-i"]`)。
- **返回**: `session_id` (str)
### `send_command`
向活动会话发送输入并等待输出。
- **参数**:
- `session_id` (str): 目标会话 ID。
- `cmd` (str): 要发送的命令字符串。
- `wait_for` (str, 可选): 要等待的正则表达式模式 (例如 `\$\s*`)。如果未提供，则默认为较短的超时时间。
- `timeout` (int, 可选): 最长等待时间（秒）。
### `read_buffer`
读取会话缓冲区中任何挂起的输出，而不发送新命令。
- **参数**: `session_id` (str)
### `kill_session`
终止特定会话。
- **参数**: `session_id` (str)
## 资源
- **`cli://{session_id}/history`**: 检索特定会话的完整交互历史记录（输入和输出）。
## 路线图
- [ ] **会话录制**：支持以标准格式（例如 [asciinema](https://asciinema.org/)）保存交互日志，以便重放和审计。
- [ ] **人工干预**：启用机制，允许用户暂停、终止或手动干预由 Agent 管理的活动 Shell 会话。
---
> [!WARNING]
> **安全警告**：此工具为连接的 LLM 提供完整的终端访问权限。LLM 将拥有与运行 MCP 服务器的用户相同的权限。仅在一个受信任的环境或沙盒容器（例如 Docker）中使用，以防止未经授权的系统修改。
