interactive-terminal

mcp-interactive-terminal

为 AI Agent（Claude Code、Cursor、Windsurf 等）提供真正的交互式终端会话的 MCP 服务。运行 REPL、SSH、数据库客户端和任何交互式 CLI——输出清晰的文本、智能检测命令完成状态，并提供 7 层安全防护。

为什么需要它

AI 编码 Agent 无法处理交互式命令。它们没有 PTY，也不支持 stdin 流。你无法通过它们运行 rails console、python、psql、ssh 或任何 REPL。这个 MCP 服务解决了这个问题。

AI Agent (Claude Code, Cursor, etc.)
    ↕  MCP (JSON-RPC over stdio)
mcp-interactive-terminal
    ↕  node-pty + xterm-headless
Interactive Process (rails console, python, psql, ssh, bash...)
    ↕
Clean text output (exactly what a human would see)

安装

Claude Code

claude mcp add terminal -- npx -y mcp-interactive-terminal

就这么简单。现在即可使用该服务。让 Claude“打开一个 python REPL 并计算 2**100”。

Cursor

前往 Settings > MCP Servers，点击 Add Server，然后输入：

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-terminal"]
    }
  }
}

Windsurf

添加到你的 MCP 配置中：

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-terminal"]
    }
  }
}

VS Code（GitHub Copilot）

添加到你的 .vscode/mcp.json：

{
  "servers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-terminal"]
    }
  }
}

任何 MCP 客户端

该服务通过 stdio 使用 Model Context Protocol 通信。任何兼容 MCP 的客户端都可以使用它，只需运行相同的 npx -y mcp-interactive-terminal 命令。

实际示例

Rails 控制台

You: "Open rails console for staging and check the user count"

Agent creates session → bash
Agent sends: cd /path/to/app && rails console -e staging
Agent sends: User.count
Agent returns: 1,847,293

Python REPL

You: "Open python and test my sorting algorithm"

Agent creates session → python3
Agent sends: def quicksort(arr): ...
Agent sends: quicksort([3, 1, 4, 1, 5, 9])
Agent returns: [1, 1, 3, 4, 5, 9]

数据库客户端

You: "Connect to postgres and show me the largest tables"

Agent creates session → psql -U myuser mydb
Agent sends: SELECT tablename, pg_size_pretty(pg_total_relation_size(tablename::text)) ...
Agent returns: formatted table of results

SSH

You: "SSH into the staging server and check disk usage"

Agent creates session → ssh [email protected]
Agent sends: df -h
Agent returns: disk usage table

Docker

You: "Open a shell in my running container and check the logs"

Agent creates session → docker exec -it my-container bash
Agent sends: tail -100 /var/log/app.log
Agent returns: last 100 log lines

Node.js REPL

You: "Open node and test the date parsing logic"

Agent creates session → node
Agent sends: new Date('2024-02-29').toISOString()
Agent returns: 2024-02-29T00:00:00.000Z

工具

该服务提供 7 个 MCP 工具：

create_session — 启动交互式进程

{ "command": "python3", "name": "my-python", "cwd": "/project" }
→ { "session_id": "a1b2c3d4", "name": "my-python", "pid": 12345 }

参数	必填	默认值	描述
command	是	—	要运行的命令（bash、python3、psql、ssh 等）
args	否	[]	命令参数
name	否	auto	易于识别的会话名称
cwd	否	server cwd	工作目录
env	否	{}	其他环境变量
cols	否	120	终端列数
rows	否	40	终端行数

send_command — 发送输入并获取输出

{ "session_id": "a1b2c3d4", "input": "1 + 1" }
→ { "output": "2", "is_complete": true, "is_alive": true }

参数	必填	默认值	描述
session_id	是	—	目标会话
input	是	—	要发送的命令/输入（会自动追加换行符）
timeout_ms	否	5000	等待输出的最长时间
max_output_chars	否	20000	超出此长度时截断输出

危险命令（rm -rf、DROP TABLE、curl|bash 等）会被拦截——Agent 必须先使用 confirm_dangerous_command。

read_output — 读取终端屏幕（只读）

{ "session_id": "a1b2c3d4" }
→ { "output": ">>> ", "is_alive": true }

可安全地自动批准——此工具只读取内容，不会发送输入。

list_sessions — 列出活动会话（只读）

→ [{ "session_id": "a1b2c3d4", "name": "my-python", "command": "python3", "pid": 12345, "is_alive": true }]

可安全地自动批准。

close_session — 终止会话

{ "session_id": "a1b2c3d4" }
→ { "success": true }

send_control — 发送控制字符

{ "session_id": "a1b2c3d4", "control": "ctrl+c" }
→ { "output": "^C\n>>>" }

支持：ctrl+c、ctrl+d、ctrl+z、ctrl+l、ctrl+r、tab、escape、up、down、left、right、enter、backspace、delete、home、end 等。

confirm_dangerous_command — 两步安全确认

{ "session_id": "a1b2c3d4", "input": "rm -rf /tmp/old", "justification": "Cleaning up stale temp files from failed build" }
→ { "output": "...", "is_complete": true, "is_alive": true }

当 send_command 检测到危险模式时必须使用。Agent 必须说明该命令为何必要。这是一个独立工具——即使 send_command 已自动批准，此工具仍需单独授权。

工作原理

两种终端模式

PTY 模式（默认）——使用 node-pty + @xterm/headless（与 VS Code 使用相同的终端模拟器）：

• 输出简洁——AI 看到的内容与人类在屏幕上看到的完全一致
• 光标定位、进度条、\r 覆盖都能正确渲染
• 完整键盘支持：方向键、Tab 补全、ctrl+c/d/z、home/end
• 终端调整大小、TUI 应用（vim、htop、top）、256 色、1000 行回滚缓冲区

管道模式（自动回退）——node-pty 无法加载时启用（例如在沙盒环境中）：

• 交互式会话仍可通过 child_process.spawn 正常工作，并自动注入标志（python -u -i、bash -i 等）
• 移除 ANSI 代码，控制键仍可使用
• 不进行终端模拟，但能满足基本需求

模式会自动选择——优先尝试 PTY，失败时切换到管道模式。

AI 看到的内容：PTY 与管道模式对比

场景	PTY 模式	管道模式
printf "\rProgress: 3/3"	Progress: 3/3	Progress: 1/3Progress: 2/3Progress: 3/3
ANSI 颜色	干净地移除	通过正则表达式移除
vim、htop、top	屏幕清晰可读	乱码
方向键、Tab 补全	可用	可用
终端调整大小	可用	无操作

智能“命令完成”检测

服务器不会盲目等待固定时长，而是采用分层策略：

1. 进程退出——如果进程已结束，则命令已完成
2. 提示符检测——启动时自动检测会话的提示符（bash $、python >>>、psql # 等），并监测其是否重新出现
3. 输出稳定——300ms 内没有新输出，即认为命令可能已完成
4. 超时——始终会在 timeout_ms 后返回，并设置 is_complete: false

安全

七层纵深防御：

层	功能	默认值
MCP 工具注解	在每个工具上设置 readOnlyHint/destructiveHint	始终启用
确认流程	危险模式需要 confirm_dangerous_command	始终启用
输入模式检测	检测 rm -rf、DROP TABLE、curl|bash 等	始终启用
命令黑名单/白名单	阻止/允许特定命令	可配置
操作系统级沙盒	通过 @anthropic-ai/sandbox-runtime 进行内核级进程沙盒隔离	关闭（选择启用）
密钥脱敏	脱敏输出中的 AWS 密钥、令牌和私钥	关闭（选择启用）
资源限制	最大会话数、输出上限、空闲超时、审计日志	始终启用

推荐权限

仅自动批准只读工具：

{
  "permissions": {
    "allow": [
      "mcp__terminal__list_sessions",
      "mcp__terminal__read_output"
    ]
  }
}

这样，send_command、create_session，尤其是 confirm_dangerous_command，始终需要人工批准。

配置

所有设置均通过环境变量进行。在 MCP 配置中传入这些变量：

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "mcp-interactive-terminal"],
      "env": {
        "MCP_TERMINAL_ALLOWED_COMMANDS": "bash,python3,node,psql",
        "MCP_TERMINAL_REDACT_SECRETS": "true",
        "MCP_TERMINAL_IDLE_TIMEOUT": "300000"
      }
    }
  }
}

变量	默认值	描述
MCP_TERMINAL_MAX_SESSIONS	10	最大并发会话数
MCP_TERMINAL_MAX_OUTPUT	20000	每次读取的最大输出字符数
MCP_TERMINAL_DEFAULT_TIMEOUT	5000	默认等待超时时间（ms）
MCP_TERMINAL_BLOCKED_COMMANDS	—	以逗号分隔的黑名单
MCP_TERMINAL_ALLOWED_COMMANDS	—	以逗号分隔的白名单（若设置，则仅允许其中的命令）
MCP_TERMINAL_ALLOWED_PATHS	—	会话可访问的路径，以逗号分隔
MCP_TERMINAL_REDACT_SECRETS	false	脱敏输出中的 AWS 密钥、令牌和私钥
MCP_TERMINAL_LOG_INPUTS	false	将所有输入记录到 stderr（用于调试）
MCP_TERMINAL_IDLE_TIMEOUT	1800000	自动关闭空闲会话（ms，默认 30min，0 = 禁用）
MCP_TERMINAL_DANGER_DETECTION	true	启用危险命令确认流程
MCP_TERMINAL_AUDIT_LOG	—	JSON 审计日志文件的路径
MCP_TERMINAL_SANDBOX	false	启用操作系统级内核沙盒隔离
MCP_TERMINAL_SANDBOX_ALLOW_WRITE	/tmp	沙盒模式下允许写入的路径
MCP_TERMINAL_SANDBOX_ALLOW_NETWORK	*	沙盒中允许访问的网络域名

故障排查

“工具未显示”／服务无提示失败

无法启动的 MCP 服务通常不会在客户端中显示错误。请检查：

# Test the server directly:
npx -y mcp-interactive-terminal

# You should see "[mcp-terminal] Starting MCP Interactive Terminal Server" on stderr.
# If you see an error, that's what's failing.

Node.js 版本过旧

该服务要求 Node.js >= 18。如果看到有关不支持的语法或缺少 API 的错误：

node --version  # Must be >= 18

# If using nvm:
nvm install 18 && nvm use 18

# If using volta:
volta install node@18

对于 nvm/volta/fnm 用户：npx 可能使用与当前 shell 不同的 Node 版本。请使用绝对路径：

{
  "mcpServers": {
    "terminal": {
      "command": "/Users/you/.nvm/versions/node/v22.0.0/bin/npx",
      "args": ["-y", "mcp-interactive-terminal"]
    }
  }
}

使用以下命令查找路径：which npx

node-pty 编译错误

node-pty 是一个需要构建工具的原生模块。如果编译失败，服务会自动回退到管道模式——交互式会话仍可正常使用，只是没有终端模拟。

如果需要完整的 PTY 支持：

# macOS:
xcode-select --install

# Ubuntu/Debian:
sudo apt-get install -y make python3 build-essential

# RHEL/Fedora:
sudo yum install -y make python3 gcc gcc-c++

会话立即终止

有些命令需要在 shell 中运行，而不是直接运行：

# Instead of:  create_session({ command: "rails console -e staging" })
# Do this:     create_session({ command: "bash" })
#              send_command({ input: "rails console -e staging" })

这是因为 create_session 会直接运行命令（类似 exec），而不会通过 shell。先启动 bash，即可获得完整的 shell 环境。

输出看起来乱码

如果输出包含转义码或显示异常，可能是处于管道模式（node-pty 加载失败）。请检查服务日志中是否有 "falling back to pipe mode"。安装构建工具（见上文）即可启用 PTY 模式。

长时间运行命令的超时时间过短

按命令增加超时时间：

{ "session_id": "...", "input": "bundle install", "timeout_ms": 60000 }

也可以通过环境变量全局设置：

{ "env": { "MCP_TERMINAL_DEFAULT_TIMEOUT": "30000" } }

与其他方案的比较

功能	mcp-interactive-terminal	特定应用的终端服务	通用 shell MCP 服务
跨平台	是	通常仅支持单个应用	因情况而异
输出整洁（xterm-headless）	是	否（屏幕抓取）	否（原始 PTY 转储）
智能完成检测	4 层算法	否	基础超时
安全层	7 层（确认流程、沙箱、脱敏等）	无	基础
危险命令确认	是（独立工具）	否	否
MCP 工具注解	是	否	否
后台会话	是	否（使用活动标签页）	是
精简 API	7 个工具	2-3 个工具	15-20+ 个工具（功能膨胀）
安装	npx -y（零配置）	需要特定应用	因情况而异

开发

git clone https://github.com/amol21p/mcp-interactive-terminal.git
cd mcp-interactive-terminal
npm install
npm run build
npm test

使用 MCP Inspector 测试：

npx @modelcontextprotocol/inspector dist/index.js

许可证

MIT