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 registry 一次並快取結果。無頭模式和 MCP 用戶端模式永遠不會檢查或列印任何內容（因此 MCP stdio 保持乾淨）。若要完全退出，請設定 NO_UPDATE_NOTIFIER=1 或傳入 --no-update-notifier。

功能

  • 完整終端機模擬：使用 xterm.js headless 進行精確的 VT100/ANSI 模擬
  • 跨平台 PTY：透過 node-pty 提供原生虛擬終端機支援（macOS、Linux、Windows）
  • MCP 協定：實作 Model Context Protocol 以整合 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 socket），然後您的 MCP 用戶端會產生第二個實例來連線到該 socket。這需要 TTY。

無頭模式（--headless）透過在內部產生嵌入式 PTY，並在單一程序中直接透過 stdio 提供 MCP 服務，消除了此需求。沒有互動式終端機工作階段，沒有 socket——只是一個自包含的 MCP 伺服器，內建終端機。

何時使用無頭模式

  • CI/CD 管線——沒有可用的 TTY
  • Docker 容器——沒有可並行執行的互動式 shell
  • 遠端/雲端環境——由自動化產生的 MCP 伺服器
  • 簡化設定——單一程序，無需 socket 協調

設定

{
  "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，包含純文字內容、游標位置和尺寸
ansiJSON，內容欄位中保留 ANSI 色彩跳脫碼
png彩色螢幕截圖為 PNG 影像（需要 @resvg/resvg-js）
{
  "name": "takeScreenshot",
  "arguments": { "format": "text" }
}

ansi 格式會從終端機的 cell 緩衝區重建 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 有三種操作模式：

模式旗標Stdin說明
互動式（預設）TTY使用者獲得 shell；AI 透過 Unix socket 連線
用戶端（預設）非 TTY連線到互動式工作階段的 socket，透過 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