交互式 Shell MCP

用于支持 TUI 的交互式 Shell 会话的 MCP 服务器。为 AI 智能体提供持久化终端、交互式提示导航、渲染屏幕读取和输出搜索功能。

演示

为什么存在此项目

大多数 AI 编码工具在隔离环境中运行 Shell 命令：每个命令都会启动一个新的 Shell，无法进行交互式提示，且 TUI 应用只会输出原始转义代码。此 MCP 服务器提供带有虚拟终端仿真器 (@xterm/headless) 的持久化 PTY 会话，以便智能体可以保持 Shell 状态、使用方向键导航交互式提示，并将渲染后的终端屏幕读取为纯文本。

三种输出模式：

快速开始

git clone https://github.com/lightos/interactive-shell-mcp.git
cd interactive-shell-mcp
npm install && npm run build
claude mcp add interactive-shell node dist/src/server.js

然后询问 Claude：“监控 htop 并告诉我什么占用了最多的 CPU”

功能

• 通过 @xterm/headless 从 TUI 应用读取渲染后的屏幕

• 所有读取工具均支持 waitForIdle（无需再通过 sleep 猜测）

• 支持文本和正则表达式模式匹配的屏幕搜索

• 支持行/列坐标的矩形区域提取

• Shell 白名单：bash, zsh, fish, sh, dash, ksh, powershell.exe, pwsh, cmd.exe

• 空闲 10 分钟后自动清理，进程退出后 60 秒内检测退出代码

• 跨平台：Unix/Linux/macOS + Windows

使用场景

• 交互式脚手架与迁移：npx create-next-app, drizzle-kit push, prisma migrate, npm init 或任何基于 inquirer/clack 的 CLI

• 系统监控：htop, btop, top, iftop, duf，支持进程搜索和区域提取

• DevOps TUI：lazydocker, lazygit, k9s, terraform console

• 远程会话：ssh 进入服务器，包括通过 SSH 运行嵌套的 TUI 应用

• 数据库 CLI：交互模式下的 psql, mysql, redis-cli, mongosh

• 网络工具：netcat/ncat, nmap, airodump-ng, tcpdump

• REPL 与调试器：python, node, irb, gdb/lldb

• 文本编辑器：vim, nano, emacs -nw

MCP 配置

Claude Code (CLI)

claude mcp add interactive-shell node /path/to/interactive-shell-mcp/dist/src/server.js

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)：

{
  "mcpServers": {
    "interactive-shell": {
      "command": "node",
      "args": ["/path/to/interactive-shell-mcp/dist/src/server.js"]
    }
  }
}

VS Code / Cursor

添加到你的 MCP 设置 (.vscode/mcp.json 或 ~/.cursor/mcp.json)：

{
  "mcpServers": {
    "interactive-shell": {
      "command": "node",
      "args": ["/path/to/interactive-shell-mcp/dist/src/server.js"]
    }
  }
}

工具参考

start_shell_session

生成带有虚拟终端仿真器的新 PTY Shell。

返回 { sessionId, cols, rows }

send_shell_input

向 PTY 写入输入。默认追加回车符。

read_shell_output

读取 PTY 的输出。三种模式：流式 (默认)、快照、屏幕。

屏幕模式在元数据中返回光标位置、终端尺寸和备用缓冲区状态。

get_screen_region

从屏幕的矩形区域提取文本。

get_screen_cursor

获取光标位置和当前行文本。

返回 { cursor: { x, y }, currentLine, isAlternateBuffer }

search_screen

在终端屏幕中搜索文本或正则表达式。最多返回 50 个匹配项。

返回 { results: [{ row, col, text }], count }

list_sessions

列出所有带有元数据的活动会话。无参数。

返回 { sessions: [{ sessionId, shell, cols, rows, isAlternateBuffer, idleSeconds }] }

resize_shell

调整活动会话的终端大小。

end_shell_session

关闭 PTY 并清理资源。

使用示例

这些示例展示了开发人员构建集成时使用的 MCP 工具调用模式。最终用户只需自然地与他们的 AI 智能体对话即可。

读取 TUI 应用

await send_shell_input(sessionId, "htop");
const { output, metadata } = await read_shell_output(sessionId, {
  mode: "screen",
  waitForIdle: 500
});
// output: rendered htop as clean text (CPU bars, process table, etc.)
// metadata.isAlternateBuffer: true (htop uses alternate screen)

// Extract just the process list (rows 6-30)
const processes = await get_screen_region(sessionId, {
  startRow: 6, startCol: 0, endRow: 30, endCol: 120,
  trimWhitespace: true
});

导航交互式提示

// Send arrow keys and enter in raw mode
await send_shell_input(sessionId, "\\x1b[B", { raw: true });  // down arrow
await send_shell_input(sessionId, " ", { raw: true });         // space to select
await send_shell_input(sessionId, "\\r", { raw: true });       // enter to confirm

// Read what the prompt looks like now
const screen = await read_shell_output(sessionId, {
  mode: "screen", waitForIdle: 300
});

等待命令输出

await send_shell_input(sessionId, "npm install");
const output = await read_shell_output(sessionId, {
  waitForIdle: 1000  // wait for 1s of silence
});

搜索内容

// Find all error lines
const errors = await search_screen(sessionId, {
  pattern: "error|Error|ERROR",
  regex: true,
  waitForIdle: 500
});
// [{ row: 12, col: 0, text: "Error" }, ...]

会话行为

• 自动清理：空闲超过 10 分钟的会话将被自动销毁

• 退出检测：当 Shell 退出时，工具会在 60 秒内返回 "Session exited with code N"，而不是通用的无效 ID 错误

• Shell 白名单：仅允许生成已知的 Shell (bash, zsh, fish, sh, dash, ksh, powershell.exe, pwsh, cmd.exe)。未知值将回退到平台默认值。

许可证

MIT