交互式外壳MCP
 ](https://nodejs.org) 
MCP服务器，用于支持TUI的交互式shell会话。为AI代理提供持久终端、交互式提示导航、渲染屏幕阅读和输出搜索。
演示
| 无MCP | 有MCP |
|---|---|
| Without MCP | With MCP |
| *“htop是交互式的，无法运行”* | *启动htop，读取屏幕，提取过程数据（2倍速度）* |
为什么存在
大多数AI编码工具独立运行shell命令：每个命令都会启动一个新的shell，交互式提示是不可能的，TUI应用程序只会转储原始转义码。此MCP服务器通过虚拟终端仿真器提供持久的PTY会话(@xterm/headless)因此，代理可以维护shell状态，使用箭头键导航交互式提示，并将渲染的终端屏幕读取为干净的文本。
三种输出模式：
| 模式 | 最适合 | 你得到什么 |
|---|---|---|
| 流媒体 | 常规命令（ls、git、npm） | 原始顺序输出，读取后清除 |
| 快照 | 实时更新应用程序（顶部，htop） | 当前终端缓冲区尾部 |
| 屏幕 | TUI应用程序、提示、任何可视化内容 | 渲染的2D文本网格（人类看到的） |
快速开始
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然后问克劳德： *“监视htop并告诉我哪些CPU使用最多”*
特性
- 通过TUI应用程序读取渲染屏幕
@xterm/headless waitForIdle在所有阅读工具中（不再在睡眠中猜测）- 使用文本和正则表达式模式匹配进行屏幕搜索
- 基于行/列坐标的矩形区域提取
- 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，或任何基于查询器/clack的CLI - 系统监控:
htop,btop,top,iftop,duf具有过程搜索和区域提取功能 - DevOps TUI:
lazydocker,lazygit,k9s,terraform console - 远程会话:
ssh进入服务器，包括通过SSH嵌套的TUI应用程序 - 数据库CLIs:
psql,mysql,redis-cli,mongosh在交互模式下 - 网络工具:
netcat/ncat,nmap,airodump-ng,tcpdump - REPL和调试器:
python,node,irb,gdb/lldb - 文本编辑器:
vim,nano,emacs -nw
MCP配置
克劳德代码（CLI）
claude mcp add interactive-shell node /path/to/interactive-shell-mcp/dist/src/server.js克劳德桌面
增添 ~/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代码/光标
添加到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。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
cols | number | no | 终端列（默认值：120，最大值：500） |
rows | number | no | 终端行（默认值：40，最大值：200） |
shell | string | no | 要使用的Shell（默认值： $SHELL 或 bash) |
cwd | string | no | 工作目录（默认：服务器cwd） |
退货 { sessionId, cols, rows }
send_shell_input
将输入写入PTY。默认情况下附加回车符。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
sessionId | string | yes | 会话ID |
input | string | yes | 要发送的文本。原始模式： \x1b[A （向上）， \x1b[B （向下）， \r （输入） |
raw | boolean | no | 发送时不附加CR。解析转义序列。（默认值：false） |
read_shell_output
读取PTY的输出。三种模式：流媒体（默认）、快照、屏幕。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
sessionId | string | yes | 会话ID |
mode | string | 否 | "streaming", "snapshot"，或 "screen" |
waitForIdle | number | no | 读取前等待N毫秒的静默（最大值：5000毫秒） |
maxBytes | number | no | 流模式的最大字节数（默认值：100KB） |
snapshotSize | number | no | 快照缓冲区大小（默认值：50KB） |
rows | number | no | 屏幕模式：起始行（从0开始） |
rowEnd | number | no | 屏幕模式：结束行（独占） |
includeEmpty | boolean | no | 屏幕模式：包括尾随空行（默认值：true） |
trimWhitespace | boolean | no | 屏幕模式：每行修剪尾随空格（默认值：false） |
屏幕模式返回元数据中的光标位置、终端尺寸和备用缓冲区状态。
get_screen_region
从屏幕的矩形区域提取文本。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
sessionId | string | yes | 会话ID |
startRow | number | yes | 起始行（从0开始，包括0） |
startCol | number | yes | 起始列（从0开始，包括0） |
endRow | number | yes | 结束行（不包括） |
endCol | number | yes | 结束列（不包括） |
trimWhitespace | boolean | no | 修剪每行尾随空格（默认值：false） |
waitForIdle | number | no | 读取前等待N毫秒的静默（最大值：5000毫秒） |
get_screen_cursor
获取光标位置和当前行文本。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
sessionId | string | yes | 会话ID |
waitForIdle | number | no | 读取前等待N毫秒的静默（最大值：5000毫秒） |
退货 { cursor: { x, y }, currentLine, isAlternateBuffer }
search_screen
在终端屏幕上搜索文本或正则表达式。最多返回50场比赛。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
sessionId | string | yes | 会话ID |
pattern | string | yes | 文本或正则表达式模式 |
regex | boolean | no | 将模式视为正则表达式（默认值：false） |
waitForIdle | number | no | 读取前等待N毫秒的静默（最大值：5000毫秒） |
退货 { results: [{ row, col, text }], count }
list_sessions
列出所有具有元数据的活动会话。没有参数。
退货 { sessions: [{ sessionId, shell, cols, rows, isAlternateBuffer, idleSeconds }] }
resize_shell
调整活动会话的终端大小。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
sessionId | string | yes | 会话ID |
cols | number | yes | 新列（1-500） |
rows | number | yes | 新行（1-200） |
end_shell_session
关闭PTY并清理资源。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
sessionId | string | yes | 会话ID |
用法示例
这些显示了构建集成的开发人员的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退出时，工具返回
"Session exited with code N"持续60秒，而不是一般的无效ID错误 - 贝壳合金：只能生成已知的shell（bash、zsh、fish、sh、dash、ksh、powershell.exe、pwsh、cmd.exe）。未知值将恢复为平台默认值。
许可证
麻省理工学院