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 เข้ากับการกำหนดค่า MCP ของเครื่องมือ AI ทุกตัวที่ติดตั้งบนเครื่องของคุณในครั้งเดียว:

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

ไคลเอนต์ที่รองรับ (แต่ละตัวจะได้รับ schema ที่ถูกต้องตามรูปแบบการกำหนดค่าของตน):

ไคลเอนต์	ไฟล์กำหนดค่า	รูปแบบ
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

สำเนา .bak ของการกำหนดค่าที่มีอยู่ก่อนจะถูกเขียนไว้ข้างไฟล์ต้นฉบับในการติดตั้งครั้งแรก รายการ terminal-mcp จะถูกเพิ่มโดยไม่รบกวนเซิร์ฟเวอร์อื่นหรือคีย์ที่ไม่เกี่ยวข้อง การรัน setup อีกครั้งจะไม่มีการเปลี่ยนแปลงใดๆ

การอัปเกรด

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

โหมดโต้ตอบจะแสดงแบนเนอร์ในการเปิดใช้ครั้งถัดไปเมื่อมีเวอร์ชันใหม่ให้ใช้งาน — terminal-mcp จะตรวจสอบ npm registry วันละครั้งและแคชผลลัพธ์ โหมด headless และโหมดไคลเอนต์ MCP จะไม่ตรวจสอบหรือแสดงสิ่งใดเลย (เพื่อให้ MCP stdio สะอาด) หากต้องการปิดการใช้งานทั้งหมด ให้ตั้งค่า NO_UPDATE_NOTIFIER=1 หรือส่ง --no-update-notifier

คุณสมบัติ

• การจำลองเทอร์มินัลเต็มรูปแบบ: ใช้ xterm.js headless เพื่อการจำลอง VT100/ANSI ที่แม่นยำ
• PTY ข้ามแพลตฟอร์ม: รองรับ pseudo-terminal ดั้งเดิมผ่าน node-pty (macOS, Linux, Windows)
• โปรโตคอล MCP: ใช้ Model Context Protocol สำหรับการรวมเข้ากับผู้ช่วย AI
• การบันทึกเซสชัน: บันทึกเซสชันเทอร์มินัลเป็นรูปแบบ asciicast สำหรับเล่นซ้ำด้วย asciinema
• API ง่ายๆ: เครื่องมือเก้าอย่างครอบคลุมการป้อนข้อมูล การสังเกต การบันทึก และวงจรชีวิตของเซสชัน
• โหมด Headless: รันเป็นเซิร์ฟเวอร์ MCP แบบสแตนด์อโลนโดยไม่ต้องใช้ TTY — เหมาะสำหรับ CI คอนเทนเนอร์ และสภาพแวดล้อมที่ไม่โต้ตอบ
• หลายเซสชัน: รันเซสชันเทอร์มินัลที่แยกจากกันหลายเซสชันในกระบวนการเดียว ระบุด้วย sessionId
• โหมด Sandbox: ข้อจำกัดด้านความปลอดภัยเพิ่มเติมสำหรับการเข้าถึงไฟล์ระบบและเครือข่าย

การสร้างจากซอร์สโค้ด

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)

โหมด Headless

โดยค่าเริ่มต้น Terminal MCP ใช้ สถาปัตยกรรมสองกระบวนการ: คุณรัน terminal-mcp ในเทอร์มินัลแบบโต้ตอบ (ซึ่งสร้าง Unix socket) จากนั้นไคลเอนต์ MCP ของคุณจะสร้างอินสแตนซ์ที่สองที่เชื่อมต่อกับ socket นั้น ซึ่งต้องใช้ TTY

โหมด Headless (--headless) ขจัดข้อกำหนดนี้โดยสร้าง PTY แบบฝังภายในและให้บริการ MCP โดยตรงผ่าน stdio ในกระบวนการเดียว ไม่ต้องมีเซสชันเทอร์มินัลแบบโต้ตอบ ไม่ต้องมี socket — เพียงเซิร์ฟเวอร์ MCP แบบครบวงจรพร้อมเทอร์มินัลในตัว

เมื่อใดควรใช้โหมด headless

• ไปป์ไลน์ CI/CD — ไม่มี TTY ให้ใช้
• คอนเทนเนอร์ Docker — ไม่มีเชลล์แบบโต้ตอบให้รันควบคู่
• สภาพแวดล้อมระยะไกล/คลาวด์ — เซิร์ฟเวอร์ 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.)

ในโหมด headless เซสชันเทอร์มินัลจะถูกเริ่มต้นทันทีเมื่อเริ่มระบบ ดังนั้นเครื่องมือทั้งหมด (type, sendKey, getContent, takeScreenshot, startRecording, stopRecording, createSession, listSessions, destroySession) พร้อมใช้งานทันที

เครื่องมือ MCP

เครื่องมืออินพุต/เอาต์พุตทั้งหมด (type, sendKey, getContent, takeScreenshot) ยอมรับอาร์กิวเมนต์ sessionId ที่ไม่บังคับ ละเว้นเพื่อกำหนดเป้าหมายเซสชันเริ่มต้น ส่ง ID ที่ส่งคืนโดย createSession เพื่อขับเคลื่อนเซสชันเฉพาะ

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	JSON พร้อมรหัสสี ANSI ที่เก็บไว้ในฟิลด์เนื้อหา
png	ภาพหน้าจอสีเป็นไฟล์ PNG (ต้องใช้ @resvg/resvg-js)

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

รูปแบบ ansi สร้างลำดับการหลบหนี SGR ขึ้นใหม่จากบัฟเฟอร์เซลล์ของเทอร์มินัล โดยรักษาคุณสมบัติสี 16 สี 256 สี และ truecolor 24 บิต พร้อมกับสไตล์ตัวหนา สลัว ตัวเอียง และขีดเส้นใต้

รูปแบบ png ส่งคืนบล็อกเนื้อหา image ของ MCP พร้อมข้อมูล PNG ที่เข้ารหัส base64 แสดงผลด้วยธีมสี 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 ขับเคลื่อนการ build ที่ใช้เวลานานในเซสชันหนึ่ง ขณะที่รันการวินิจฉัยในอีกเซสชันหนึ่ง โดยไม่มีการแทรกสลับคำสั่ง

โหมด Sandbox

รันเทอร์มินัลด้วยการจำกัดการเข้าถึงไฟล์ระบบและเครือข่าย:

# Interactive permission configuration
terminal-mcp --sandbox

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

โหมดโต้ตอบแสดงกล่องโต้ตอบ TUI เพื่อกำหนดค่าการอนุญาต:

- **อ่าน/เขียน**: การเข้าถึงเต็มรูปแบบ (ไดเรกทอรีปัจจุบัน, /tmp, แคช) - **อ่านอย่างเดียว**: อ่านได้แต่ไม่สามารถแก้ไขได้ (ไดเรกทอรีบ้าน) - **ถูกบล็อก**: ไม่มีการเข้าถึง (คีย์ SSH, ข้อมูลประจำตัวคลาวด์, โทเค็นการตรวจสอบสิทธิ์)

ตัวอย่างไฟล์กำหนดค่า:

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

การรองรับแพลตฟอร์ม:

• macOS: รองรับเต็มรูปแบบผ่าน sandbox-exec (Seatbelt)
• Linux: รองรับเต็มรูปแบบผ่าน bubblewrap (ต้องติดตั้ง bwrap)
• Windows: การลดระดับอย่างราบรื่น (รันโดยไม่มี sandbox)

ดู เอกสาร Sandbox สำหรับตัวเลือกการกำหนดค่าโดยละเอียด

การบันทึก

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	ผู้ใช้ได้รับเชลล์ AI เชื่อมต่อผ่าน Unix socket
ไคลเอนต์	(ค่าเริ่มต้น)	ไม่ใช่ TTY	เชื่อมต่อกับ socket ของเซสชันโต้ตอบ ให้บริการ MCP ผ่าน stdio
Headless	--headless	ใดๆ	ครบวงจร: PTY แบบฝัง + เซิร์ฟเวอร์ MCP ผ่าน stdio

โหมด Headless (แนะนำสำหรับการกำหนดค่า 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 สำหรับเอกสารโดยละเอียด:

• ภาพรวม
• การติดตั้ง
• เอกสารอ้างอิงเครื่องมือ
• การบันทึก
• การกำหนดค่า
• โหมด Sandbox
• ตัวอย่าง
• สถาปัตยกรรม

ข้อกำหนด

• Node.js 18.0.0 หรือใหม่กว่า
• Windows 10 เวอร์ชัน 1809 หรือใหม่กว่า (สำหรับการรองรับ ConPTY)

สัญญาอนุญาต

MIT