Terminal MCP

Cho AI xem và tương tác với terminal của bạn.

Terminal MCP cung cấp cho LLM một góc nhìn chung về phiên terminal của bạn. Hoàn hảo để gỡ lỗi các ứng dụng CLI và TUI theo thời gian thực, hoặc để AI tự động điều khiển các công cụ dựa trên terminal.

Cài đặt

npm install -g @ellery/terminal-mcp

Hoặc qua script cài đặt:

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

Cấu hình các công cụ AI của bạn

Kết nối terminal-mcp vào cấu hình MCP của mọi công cụ AI được cài đặt trên máy của bạn chỉ trong một lần:

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

Các client được hỗ trợ (mỗi client nhận đúng schema cho định dạng cấu hình của nó):

Client	Tệp cấu hình	Định dạng
OpenAI Codex CLI	~/.codex/config.toml	TOML
GitHub Copilot CLI	~/.copilot/mcp-config.json	JSON
Gemini CLI	~/.gemini/settings.json	JSON
OpenCode	~/.config/opencode/opencode.json	JSON
Claude Code	~/.claude.json	JSON
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)	JSON

Một .bak của bất kỳ cấu hình nào có sẵn sẽ được ghi bên cạnh bản gốc khi cài đặt lần đầu. Mục terminal-mcp được thêm vào mà không ảnh hưởng đến các server hoặc khóa không liên quan khác; chạy setup lại là một thao tác không làm gì cả.

Nâng cấp

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

Chế độ tương tác sẽ in một banner ở lần khởi chạy tiếp theo khi có bản phát hành mới hơn — terminal-mcp kiểm tra npm registry mỗi ngày một lần và lưu kết quả vào bộ nhớ đệm. Chế độ headless và MCP-client không bao giờ kiểm tra hoặc in bất cứ điều gì (để MCP stdio luôn sạch). Để từ chối hoàn toàn, hãy đặt NO_UPDATE_NOTIFIER=1 hoặc truyền --no-update-notifier.

Tính năng

• Giả lập Terminal đầy đủ: Sử dụng xterm.js headless để giả lập VT100/ANSI chính xác
• PTY đa nền tảng: Hỗ trợ pseudo-terminal gốc qua node-pty (macOS, Linux, Windows)
• Giao thức MCP: Triển khai Model Context Protocol để tích hợp trợ lý AI
• Ghi phiên: Ghi phiên terminal sang định dạng asciicast để phát lại với asciinema
• API đơn giản: Chín công cụ bao gồm nhập liệu, quan sát, ghi và vòng đời phiên
• Chế độ Headless: Chạy như một MCP server độc lập không cần TTY — lý tưởng cho CI, container và môi trường không tương tác
• Đa phiên: Chạy nhiều phiên terminal cô lập trong một tiến trình, được định địa chỉ bằng sessionId
• Chế độ Sandbox: Các hạn chế bảo mật tùy chọn cho truy cập hệ thống tệp và mạng

Xây dựng từ mã nguồn

npm install
npm run build

Cách sử dụng

Cấu hình MCP

Thêm vào cài đặt MCP client của bạn:

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

Với các tùy chọn tùy chỉnh:

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

Tùy chọn dòng lệnh

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)

Chế độ Headless

Theo mặc định, Terminal MCP sử dụng kiến trúc hai tiến trình: bạn chạy terminal-mcp trong một terminal tương tác (tạo một Unix socket), sau đó MCP client của bạn tạo một phiên bản thứ hai kết nối với socket đó. Điều này yêu cầu một TTY.

Chế độ headless (--headless) loại bỏ yêu cầu này bằng cách tạo một PTY nhúng bên trong và phục vụ MCP trực tiếp qua stdio trong một tiến trình duy nhất. Không cần phiên terminal tương tác, không cần socket — chỉ là một MCP server tự chứa với một terminal tích hợp.

Khi nào nên dùng chế độ headless

• Đường ống CI/CD — không có TTY
• Container Docker — không có shell tương tác để chạy cùng
• Môi trường từ xa/đám mây — MCP server được tạo bởi tự động hóa
• Thiết lập đơn giản — một tiến trình duy nhất, không cần phối hợp socket

Cấu hình

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

Cách hoạt động

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.)

Trong chế độ headless, phiên terminal được khởi tạo ngay khi khởi động, vì vậy tất cả các công cụ (type, sendKey, getContent, takeScreenshot, startRecording, stopRecording, createSession, listSessions, destroySession) đều có sẵn ngay lập tức.

Công cụ MCP

Tất cả các công cụ nhập/xuất (type, sendKey, getContent, takeScreenshot) chấp nhận một đối số sessionId tùy chọn. Bỏ qua để nhắm đến phiên mặc định; truyền ID được trả về bởi createSession để điều khiển một phiên cụ thể.

type

Gửi văn bản nhập vào terminal.

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

sendKey

Gửi các phím đặc biệt hoặc tổ hợp phím.

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

Các phím được hỗ trợ:

• Cơ bản: Enter, Tab, Escape, Backspace, Delete
• Mũi tên: ArrowUp, ArrowDown, ArrowLeft, ArrowRight
• Điều hướng: Home, End, PageUp, PageDown, Insert
• Chức năng: F1 đến F12
• Điều khiển: Ctrl+A đến Ctrl+Z, Ctrl+C, Ctrl+D, v.v.

getContent

Lấy bộ đệm terminal dưới dạng văn bản thuần.

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

takeScreenshot

Chụp trạng thái terminal. Hỗ trợ ba định dạng đầu ra:

Định dạng	Mô tả
text (mặc định)	JSON với nội dung văn bản thuần, vị trí con trỏ và kích thước
ansi	JSON với mã thoát màu ANSI được giữ nguyên trong trường nội dung
png	Ảnh chụp màn hình màu dưới dạng PNG (yêu cầu @resvg/resvg-js)

{
  "name": "takeScreenshot",
  "arguments": { "format": "text" }
}

Định dạng ansi tái tạo các chuỗi thoát SGR từ bộ đệm ô của terminal, giữ nguyên các thuộc tính màu 16-bit, 256-bit và truecolor 24-bit cùng với các kiểu đậm, mờ, nghiêng và gạch chân.

Định dạng png trả về một khối nội dung image của MCP với dữ liệu PNG mã hóa base64, được hiển thị với chủ đề màu One Dark và khung cửa sổ kiểu macOS.

startRecording

Bắt đầu ghi đầu ra terminal vào tệp asciicast v2.

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

Các tùy chọn:

• mode: always (lưu tất cả) hoặc on-failure (chỉ lưu khi thoát với mã khác không)
• outputDir: Thư mục đầu ra tùy chỉnh
• idleTimeLimit: Số giây tối đa giữa các sự kiện (giới hạn thời gian tạm dừng khi phát lại)
• maxDuration: Tự động dừng sau N giây
• inactivityTimeout: Tự động dừng sau N giây không có đầu ra

stopRecording

Dừng ghi và hoàn thiện tệp asciicast.

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

createSession

Tạo một phiên terminal mới và trả về siêu dữ liệu của nó. Sử dụng sessionId được trả về để nhắm đến phiên này trong các lệnh gọi công cụ tiếp theo.

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

Tất cả các đối số đều tùy chọn. Trả về:

{
  "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

Liệt kê tất cả các phiên đang hoạt động bao gồm cả phiên mặc định. Báo cáo các giới hạn đã cấu hình.

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

destroySession

Hủy một phiên theo ID. Phiên mặc định không thể bị hủy.

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

Đa phiên

Theo mặc định, mọi lệnh gọi công cụ không có sessionId nhắm đến một phiên mặc định được tự động tạo — hành vi giống như dự án vẫn luôn có. Truyền sessionId để điều khiển nhiều PTY cô lập từ một tiến trình.

• Phiên mặc định được tạo khi sử dụng lần đầu và không thể bị hủy.
• Các phiên bổ sung được tạo bởi createSession và được theo dõi cho đến khi bị hủy hoặc bị loại bỏ do không hoạt động (--session-idle-timeout, mặc định 600 giây).
• Các phiên đồng thời được giới hạn ở --max-sessions (mặc định 5).
• Một bản ghi đang hoạt động sẽ thu thập đầu ra từ tất cả các phiên trong tiến trình.

Trường hợp sử dụng điển hình: một tác nhân AI điều khiển một bản dựng chạy lâu trong một phiên trong khi chạy chẩn đoán trong một phiên khác, mà không bị trộn lẫn lệnh.

Chế độ Sandbox

Chạy terminal với quyền truy cập hệ thống tệp và mạng bị hạn chế:

# Interactive permission configuration
terminal-mcp --sandbox

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

Chế độ tương tác hiển thị hộp thoại TUI để cấu hình quyền:

- **Đọc/Ghi**: Truy cập đầy đủ (thư mục hiện tại, /tmp, bộ nhớ đệm) - **Chỉ đọc**: Có thể đọc nhưng không thể sửa đổi (thư mục chính) - **Bị chặn**: Không có quyền truy cập (khóa SSH, thông tin xác thực đám mây, mã thông báo xác thực)

Tệp cấu hình ví dụ:

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

Hỗ trợ nền tảng:

• macOS: Hỗ trợ đầy đủ qua sandbox-exec (Seatbelt)
• Linux: Hỗ trợ đầy đủ qua bubblewrap (yêu cầu bwrap được cài đặt)
• Windows: Dự phòng an toàn (chạy không có sandbox)

Xem Tài liệu Sandbox để biết các tùy chọn cấu hình chi tiết.

Ghi

Terminal MCP có thể ghi phiên sang định dạng asciicast v2, tương thích với asciinema để phát lại.

Bắt đầu nhanh

# 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>

Phát lại

Cài đặt asciinema để phát lại các bản ghi:

# 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

Chế độ ghi

• always (mặc định): Lưu mọi bản ghi
• on-failure: Chỉ lưu nếu phiên thoát với mã khác không (hữu ích để gỡ lỗi các lần chạy CI thất bại)

# Only save recordings when something fails
terminal-mcp --record=on-failure

Ghi bằng công cụ MCP

Trợ lý AI cũng có thể điều khiển việc ghi theo chương trình qua các công cụ MCP:

1. Gọi startRecording để bắt đầu thu thập
2. Thực hiện các thao tác terminal
3. Gọi stopRecording để hoàn thiện và lưu

Điều này cho phép các quy trình làm việc do AI điều khiển như "ghi lại phiên gỡ lỗi này" hoặc "chụp bản demo này".

Kiến trúc

Terminal MCP có ba chế độ hoạt động:

Chế độ	Cờ	Stdin	Mô tả
Tương tác	(mặc định)	TTY	Người dùng có shell; AI kết nối qua Unix socket
Client	(mặc định)	không phải TTY	Kết nối đến socket của phiên tương tác, phục vụ MCP qua stdio
Headless	--headless	bất kỳ	Tự chứa: PTY nhúng + MCP server qua stdio

Chế độ Headless (được khuyến nghị cho cấu hình 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.)

Chế độ Tương tác + Client (hai tiến trình)

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)

Phiên ví dụ

# 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":{}}}

Phát triển

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

Tài liệu

Xem thư mục docs để biết tài liệu chi tiết:

• Tổng quan
• Cài đặt
• Tham chiếu công cụ
• Ghi
• Cấu hình
• Chế độ Sandbox
• Ví dụ
• Kiến trúc

Yêu cầu

• Node.js 18.0.0 trở lên
• Windows 10 phiên bản 1809 trở lên (để hỗ trợ ConPTY)

Giấy phép

MIT