Terminal MCP

官方

为AI助手提供终端会话的共享实时视图，用于调试CLI和TUI，或实现自主终端控制。

GitHub
132
试用此 MCP赞助

你可以用 Terminal MCP 做什么？

  • 输入命令并发送按键 — 让 AI 通过 type 和 sendKey 运行 shell 命令，包括特殊按键如 Enter 或 Ctrl+C。
  • 读取终端输出 — 使用 getContent 将当前终端缓冲区作为纯文本检索，或通过 takeScreenshot 以 text、ansi 或 png 格式捕获截图。
  • 录制并回放会话 — 使用 startRecording 和 stopRecording 开始和停止 asciicast v2 录制，然后通过 asciinema 回放。
  • 管理多个会话 — 使用 createSession 创建隔离的终端会话，通过 listSessions 列出活动会话，并使用 destroySession 清理，每个会话通过 sessionId 标识。

文档

Terminal MCP

让 AI 查看并与你的终端交互。

Terminal MCP 为 LLM 提供终端会话的共享视图。非常适合实时调试 CLI 和 TUI 应用程序，或让 AI 自主驱动基于终端的工具。

安装

npm install -g @ellery/terminal-mcp

或通过安装脚本：

curl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/install.sh | bash

配置你的 AI 工具

将 terminal-mcp 一次性接入你机器上安装的每个 AI 工具的 MCP 配置：

terminal-mcp setup                      # detect & install for all detected tools
terminal-mcp setup --dry-run            # preview without writing
terminal-mcp setup --client claude-code,gemini   # specific tools only
terminal-mcp setup --uninstall          # remove the entry from each tool

支持的客户端（每个客户端都会获得适合其配置格式的正确模式）：

客户端配置文件格式
OpenAI Codex CLI~/.codex/config.tomlTOML
GitHub Copilot CLI~/.copilot/mcp-config.jsonJSON
Gemini CLI~/.gemini/settings.jsonJSON
OpenCode~/.config/opencode/opencode.jsonJSON
Claude Code~/.claude.jsonJSON
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json（macOS）/ %APPDATA%\Claude\claude_desktop_config.json（Windows）JSON

首次安装时，任何已有配置的 .bak 都会写在原始文件旁边。terminal-mcp 条目会被添加，而不会干扰其他服务器或不相关的键；再次运行 setup 是空操作。

升级

npm install -g @ellery/terminal-mcp@latest

交互模式会在下次启动时打印横幅，提示有更新版本可用——terminal-mcp 每天检查一次 npm 注册表并缓存结果。无头模式和 MCP 客户端模式从不检查或打印任何内容（因此 MCP stdio 保持干净）。要完全退出，请设置 NO_UPDATE_NOTIFIER=1 或传递 --no-update-notifier。

功能

  • 完整终端模拟：使用 xterm.js 无头模式进行精确的 VT100/ANSI 模拟
  • 跨平台 PTY：通过 node-pty 提供原生伪终端支持（macOS、Linux、Windows）
  • MCP 协议：实现模型上下文协议，用于 AI 助手集成
  • 会话录制：将会话录制为 asciicast 格式，可使用 asciinema 播放
  • 简单 API：九个工具，涵盖输入、观察、录制和会话生命周期
  • 无头模式：作为独立 MCP 服务器运行，无需 TTY——非常适合 CI、容器和非交互环境
  • 多会话：在一个进程中运行多个隔离的终端会话，通过 sessionId 寻址
  • 沙盒模式：可选的文件和网络访问安全限制

从源码构建

npm install
npm run build

用法

MCP 配置

添加到你的 MCP 客户端设置中：

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp"
    }
  }
}

使用自定义选项：

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp",
      "args": ["--cols", "100", "--rows", "30", "--shell", "/bin/zsh"]
    }
  }
}

命令行选项

terminal-mcp [OPTIONS]

Options:
  --cols <number>        Terminal width in columns (default: 120)
  --rows <number>        Terminal height in rows (default: 40)
  --shell <path>         Shell to use (default: $SHELL or bash)
  --headless             Run in headless mode (embedded PTY + MCP over stdio, no TTY needed)
  --sandbox              Enable sandbox mode (restricts filesystem/network)
  --sandbox-config <path> Load sandbox config from JSON file
  --version, -v          Show version number
  --help, -h             Show help message

Recording Options:
  --record [mode]     Enable recording (default mode: always)
                      Modes: always, on-failure, off
  --record-dir <dir>  Recording output directory
                      (default: ~/.local/state/terminal-mcp/recordings)
  --idle-time-limit <sec>   Max idle time between events (default: 2s)
  --max-duration <sec>      Max recording duration (default: 3600s)
  --inactivity-timeout <sec>  Stop after no output (default: 600s)

Multi-Session Options:
  --max-sessions <n>           Max concurrent sessions (default: 5)
  --session-idle-timeout <sec> Idle non-default sessions are auto-destroyed
                               after this period (default: 600s)

无头模式

默认情况下，Terminal MCP 使用双进程架构：你在交互式终端中运行 terminal-mcp（这会创建一个 Unix 套接字），然后你的 MCP 客户端生成第二个实例连接到该套接字。这需要 TTY。

无头模式（--headless）通过内部生成嵌入式 PTY 并在单进程中直接通过 stdio 提供 MCP 服务，消除了这一要求。无需交互式终端会话，无需套接字——只需一个自带终端的自包含 MCP 服务器。

何时使用无头模式

  • CI/CD 流水线——没有可用的 TTY
  • Docker 容器——没有可并行的交互式 shell
  • 远程/云环境——由自动化生成的 MCP 服务器
  • 简化设置——单进程，无需套接字协调

配置

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp",
      "args": ["--headless", "--cols", "120", "--rows", "40"]
    }
  }
}

工作原理

MCP Client (Claude Code, etc.)
    │ STDIO (JSON-RPC)
    ▼
terminal-mcp --headless
    ├── MCP Server (stdio transport)
    ├── Terminal Emulator (@xterm/headless)
    └── Embedded PTY (node-pty)
            │
            ▼
        Shell Process (bash, zsh, etc.)

在无头模式下，终端会话在启动时立即初始化，因此所有工具（type、sendKey、getContent、takeScreenshot、startRecording、stopRecording、createSession、listSessions、destroySession）立即可用。

MCP 工具

所有输入/输出工具（type、sendKey、getContent、takeScreenshot）都接受可选的 sessionId 参数。省略它以定位默认会话；传递 createSession 返回的 ID 以驱动特定会话。

type

向终端发送文本输入。

{
  "name": "type",
  "arguments": {
    "text": "echo hello"
  }
}

sendKey

发送特殊键或组合键。

{
  "name": "sendKey",
  "arguments": {
    "key": "Enter"
  }
}

支持的按键：

  • 基本：Enter、Tab、Escape、Backspace、Delete
  • 方向：ArrowUp、ArrowDown、ArrowLeft、ArrowRight
  • 导航：Home、End、PageUp、PageDown、Insert
  • 功能：F1 到 F12
  • 控制：Ctrl+A 到 Ctrl+Z、Ctrl+C、Ctrl+D 等。

getContent

以纯文本形式获取终端缓冲区。

{
  "name": "getContent",
  "arguments": {
    "visibleOnly": false
  }
}

takeScreenshot

捕获终端状态。支持三种输出格式：

格式描述
text（默认）包含纯文本内容、光标位置和尺寸的 JSON
ansi内容字段中保留 ANSI 颜色转义码的 JSON
png彩色截图，PNG 图像（需要 @resvg/resvg-js）
{
  "name": "takeScreenshot",
  "arguments": { "format": "text" }
}

ansi 格式从终端的单元格缓冲区重建 SGR 转义序列，保留 16 色、256 色和 24 位真彩色属性，以及粗体、暗淡、斜体和下划线样式。

png 格式返回一个 MCP image 内容块，包含 base64 编码的 PNG 数据，使用 One Dark 配色方案和 macOS 风格窗口边框渲染。

startRecording

开始将终端输出录制到 asciicast v2 文件。

{
  "name": "startRecording",
  "arguments": {
    "mode": "always",
    "idleTimeLimit": 2,
    "maxDuration": 3600
  }
}

选项：

  • mode：always（保存全部）或 on-failure（仅在非零退出时保存）
  • outputDir：自定义输出目录
  • idleTimeLimit：事件之间的最大秒数（限制播放中的暂停）
  • maxDuration：N 秒后自动停止
  • inactivityTimeout：无输出 N 秒后自动停止

stopRecording

停止录制并完成 asciicast 文件。

{
  "name": "stopRecording",
  "arguments": {
    "recordingId": "abc123"
  }
}

createSession

创建新的终端会话并返回其元数据。使用返回的 sessionId 在后续工具调用中定位此会话。

{
  "name": "createSession",
  "arguments": {
    "shell": "/bin/zsh",
    "cols": 100,
    "rows": 30
  }
}

所有参数都是可选的。返回：

{
  "sessionId": "3029d",
  "shell": "/bin/zsh",
  "cols": 100,
  "rows": 30,
  "createdAt": "2026-04-25T12:58:01.072Z",
  "lastActivityAt": "2026-04-25T12:58:01.072Z",
  "isDefault": false
}

listSessions

列出所有活动会话，包括默认会话。报告配置的限制。

{ "name": "listSessions", "arguments": {} }

destroySession

按 ID 销毁会话。默认会话无法销毁。

{
  "name": "destroySession",
  "arguments": { "sessionId": "3029d" }
}

多会话

默认情况下，每个没有 sessionId 的工具调用都针对一个自动创建的默认会话——这与项目一直以来的行为相同。传递 sessionId 以从一个进程驱动多个隔离的 PTY。

  • 默认会话在首次使用时创建，无法销毁。
  • 其他会话由 createSession 创建，并跟踪直到被销毁或空闲驱逐（--session-idle-timeout，默认 600 秒）。
  • 并发会话上限为 --max-sessions（默认 5）。
  • 活动录制会捕获进程中所有会话的输出。

典型用例：AI 代理在一个会话中驱动长时间运行的构建，同时在另一个会话中运行诊断，而不会出现命令交错。

沙盒模式

使用受限的文件和网络访问运行终端：

# Interactive permission configuration
terminal-mcp --sandbox

# With a config file
terminal-mcp --sandbox --sandbox-config ~/.terminal-mcp-sandbox.json

交互模式显示 TUI 对话框以配置权限：

Sandbox Permissions Dialog

- **读/写**：完全访问（当前目录、/tmp、缓存） - **只读**：可以读取但不能修改（主目录） - **阻止**：无访问权限（SSH 密钥、云凭据、认证令牌）

示例配置文件：

{
  "filesystem": {
    "readWrite": [".", "/tmp", "~/.cache"],
    "readOnly": ["~"],
    "blocked": ["~/.ssh", "~/.aws", "~/.gnupg"]
  },
  "network": {
    "mode": "all"
  }
}

平台支持：

  • macOS：通过 sandbox-exec（Seatbelt）完全支持
  • Linux：通过 bubblewrap 完全支持（需要安装 bwrap）
  • Windows：优雅降级（无沙盒运行）

有关详细配置选项，请参阅 沙盒文档。

录制

Terminal MCP 可以将会话录制为 asciicast v2 格式，兼容 asciinema 播放。

快速开始

# Start with recording enabled
terminal-mcp --record

# Run your commands, then exit
exit

# Output shows the saved file path:
# Recordings saved:
#   ~/.local/state/terminal-mcp/recordings/20240115_143022.cast
#
# Play with: asciinema play <file>

播放

安装 asciinema 以播放录制内容：

# macOS
brew install asciinema

# Linux/pip
pip install asciinema

# Play a recording
asciinema play ~/.local/state/terminal-mcp/recordings/20240115_143022.cast

# Play at 2x speed
asciinema play -s 2 recording.cast

录制模式

  • always（默认）：保存每次录制
  • on-failure：仅在会话以非零代码退出时保存（用于调试失败的 CI 运行）
# Only save recordings when something fails
terminal-mcp --record=on-failure

MCP 工具录制

AI 助手还可以通过 MCP 工具以编程方式控制录制：

  1. 调用 startRecording 开始捕获
  2. 执行终端操作
  3. 调用 stopRecording 完成并保存

这支持 AI 驱动的工作流，如“录制此调试会话”或“捕获此演示”。

架构

Terminal MCP 有三种操作模式：

模式标志标准输入描述
交互式（默认）TTY用户获得 shell；AI 通过 Unix 套接字连接
客户端（默认）非 TTY连接到交互式会话的套接字，通过 stdio 提供 MCP 服务
无头--headless任意自包含：嵌入式 PTY + 通过 stdio 的 MCP 服务器

无头模式（推荐用于 MCP 配置）

MCP Client (Claude Code, etc.)
    │ STDIO (JSON-RPC)
    ▼
terminal-mcp --headless
    ├── MCP SDK (@modelcontextprotocol/sdk)
    ├── Terminal Emulator (@xterm/headless)
    └── Embedded PTY (node-pty)
            │
            ▼
        Shell Process (bash, zsh, etc.)

交互式 + 客户端模式（双进程）

terminal-mcp (interactive, in your terminal)
    ├── User shell (stdin/stdout)
    └── Unix socket server (/tmp/terminal-mcp.sock)
            ▲
            │ JSON-RPC over socket
            ▼
terminal-mcp (client, spawned by MCP client)
    └── MCP server (stdio transport)

示例会话

# Type a command
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"type","arguments":{"text":"ls -la"}}}

# Send Enter key
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sendKey","arguments":{"key":"Enter"}}}

# Get the output
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"getContent","arguments":{}}}

开发

npm run build    # Compile TypeScript
npm run dev      # Run with tsx (development)

文档

有关详细文档，请参阅 docs 文件夹：

要求

  • Node.js 18.0.0 或更高版本
  • Windows 10 版本 1809 或更高版本（用于 ConPTY 支持）

许可证

MIT