Terminal MCP

Biarkan AI melihat dan berinteraksi dengan terminal Anda.

Terminal MCP memberikan LLM tampilan bersama dari sesi terminal Anda. Sempurna untuk men-debug aplikasi CLI dan TUI secara real-time, atau membiarkan AI menggerakkan alat berbasis terminal secara mandiri.

Instalasi

npm install -g @ellery/terminal-mcp

Atau melalui skrip instalasi:

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

Konfigurasikan alat AI Anda

Hubungkan terminal-mcp ke konfigurasi MCP dari setiap alat AI yang terpasang di mesin Anda sekaligus:

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

Klien yang didukung (masing-masing mendapatkan skema yang tepat untuk format konfigurasinya):

Klien	File Konfigurasi	Format
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

Salinan .bak dari konfigurasi yang sudah ada ditulis di samping file asli pada instalasi pertama. Entri terminal-mcp ditambahkan tanpa mengganggu server lain atau kunci yang tidak terkait; menjalankan setup lagi tidak akan melakukan apa pun.

Peningkatan Versi

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

Mode interaktif akan menampilkan banner pada peluncuran berikutnya ketika versi terbaru tersedia — terminal-mcp memeriksa registry npm sekali sehari dan menyimpan hasilnya dalam cache. Mode headless dan klien MCP tidak pernah memeriksa atau menampilkan apa pun (sehingga stdio MCP tetap bersih). Untuk menonaktifkan sepenuhnya, atur NO_UPDATE_NOTIFIER=1 atau berikan --no-update-notifier.

Fitur

• Emulasi Terminal Penuh: Menggunakan xterm.js headless untuk emulasi VT100/ANSI yang akurat
• PTY Lintas Platform: Dukungan pseudo-terminal asli melalui node-pty (macOS, Linux, Windows)
• Protokol MCP: Mengimplementasikan Model Context Protocol untuk integrasi asisten AI
• Perekaman Sesi: Rekam sesi terminal ke format asciicast untuk diputar ulang dengan asciinema
• API Sederhana: Sembilan alat yang mencakup input, observasi, perekaman, dan siklus hidup sesi
• Mode Headless: Jalankan sebagai server MCP mandiri tanpa TTY — ideal untuk CI, kontainer, dan lingkungan non-interaktif
• Multi-Sesi: Jalankan beberapa sesi terminal terisolasi dalam satu proses, dialamatkan dengan sessionId
• Mode Sandbox: Pembatasan keamanan opsional untuk akses filesystem dan jaringan

Membangun dari Sumber

npm install
npm run build

Penggunaan

Konfigurasi MCP

Tambahkan ke pengaturan klien MCP Anda:

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

Dengan opsi kustom:

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

Opsi Baris Perintah

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)

Mode Headless

Secara default, Terminal MCP menggunakan arsitektur dua proses: Anda menjalankan terminal-mcp di terminal interaktif (yang membuat Unix socket), kemudian klien MCP Anda memunculkan instance kedua yang terhubung ke socket tersebut. Ini memerlukan TTY.

Mode headless (--headless) menghilangkan kebutuhan ini dengan memunculkan PTY tertanam secara internal dan melayani MCP langsung melalui stdio dalam satu proses. Tanpa sesi terminal interaktif, tanpa socket — hanya server MCP mandiri dengan terminal bawaan.

Kapan menggunakan mode headless

• Pipeline CI/CD — tidak ada TTY yang tersedia
• Kontainer Docker — tidak ada shell interaktif untuk dijalankan berdampingan
• Lingkungan jarak jauh/cloud — server MCP dimunculkan oleh otomatisasi
• Pengaturan yang disederhanakan — satu proses, tanpa koordinasi socket

Konfigurasi

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

Cara kerjanya

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

Dalam mode headless, sesi terminal diinisialisasi secara proaktif saat startup, sehingga semua alat (type, sendKey, getContent, takeScreenshot, startRecording, stopRecording, createSession, listSessions, destroySession) tersedia segera.

Alat MCP

Semua alat input/output (type, sendKey, getContent, takeScreenshot) menerima argumen sessionId opsional. Hilangkan untuk menargetkan sesi default; berikan ID yang dikembalikan oleh createSession untuk menggerakkan sesi tertentu.

type

Kirim input teks ke terminal.

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

sendKey

Kirim tombol khusus atau kombinasi tombol.

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

Tombol yang didukung:

• Dasar: Enter, Tab, Escape, Backspace, Delete
• Panah: ArrowUp, ArrowDown, ArrowLeft, ArrowRight
• Navigasi: Home, End, PageUp, PageDown, Insert
• Fungsi: F1 hingga F12
• Kontrol: Ctrl+A hingga Ctrl+Z, Ctrl+C, Ctrl+D, dll.

getContent

Dapatkan buffer terminal sebagai teks biasa.

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

takeScreenshot

Tangkap status terminal. Mendukung tiga format output:

Format	Deskripsi
text (default)	JSON dengan konten teks biasa, posisi kursor, dan dimensi
ansi	JSON dengan kode warna ANSI yang dipertahankan di kolom konten
png	Tangkapan layar berwarna sebagai gambar PNG (memerlukan @resvg/resvg-js)

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

Format ansi merekonstruksi urutan escape SGR dari buffer sel terminal, mempertahankan atribut 16-warna, 256-warna, dan truecolor 24-bit bersama dengan gaya tebal, redup, miring, dan garis bawah.

Format png mengembalikan blok konten MCP image dengan data PNG berenkode base64, dirender dengan tema warna One Dark dan bingkai jendela bergaya macOS.

startRecording

Mulai merekam output terminal ke file asciicast v2.

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

Opsi:

• mode: always (simpan semua) atau on-failure (simpan hanya saat keluar dengan kode non-nol)
• outputDir: Direktori output kustom
• idleTimeLimit: Detik maksimum antara peristiwa (membatasi jeda dalam pemutaran)
• maxDuration: Berhenti otomatis setelah N detik
• inactivityTimeout: Berhenti otomatis setelah N detik tanpa output

stopRecording

Hentikan perekaman dan finalisasi file asciicast.

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

createSession

Buat sesi terminal baru dan kembalikan metadatanya. Gunakan sessionId yang dikembalikan untuk menargetkan sesi ini dalam panggilan alat berikutnya.

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

Semua argumen bersifat opsional. Mengembalikan:

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

Daftarkan semua sesi aktif termasuk sesi default. Melaporkan batas yang dikonfigurasi.

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

destroySession

Hancurkan sesi berdasarkan ID. Sesi default tidak dapat dihancurkan.

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

Multi-Sesi

Secara default, setiap panggilan alat tanpa sessionId menargetkan satu sesi default yang dibuat otomatis — perilaku yang sama seperti yang selalu dimiliki proyek ini. Berikan sessionId untuk menggerakkan beberapa PTY terisolasi dari satu proses.

• Sesi default dibuat pada penggunaan pertama dan tidak dapat dihancurkan.
• Sesi tambahan dibuat oleh createSession dan dilacak hingga dihancurkan atau diusir karena idle (--session-idle-timeout, default 600 detik).
• Sesi bersamaan dibatasi maksimal --max-sessions (default 5).
• Perekaman aktif menangkap output dari semua sesi dalam proses.

Kasus penggunaan umum: agen AI menggerakkan build berjalan lama di satu sesi sambil menjalankan diagnostik di sesi lain, tanpa interleaving perintah.

Mode Sandbox

Jalankan terminal dengan akses filesystem dan jaringan yang dibatasi:

# Interactive permission configuration
terminal-mcp --sandbox

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

Mode interaktif menampilkan dialog TUI untuk mengonfigurasi izin:

- **Baca/Tulis**: Akses penuh (direktori saat ini, /tmp, cache) - **Hanya-Baca**: Dapat membaca tetapi tidak mengubah (direktori home) - **Diblokir**: Tanpa akses (kunci SSH, kredensial cloud, token autentikasi)

Contoh file konfigurasi:

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

Dukungan platform:

• macOS: Dukungan penuh melalui sandbox-exec (Seatbelt)
• Linux: Dukungan penuh melalui bubblewrap (memerlukan bwrap terpasang)
• Windows: Fallback yang anggun (berjalan tanpa sandbox)

Lihat Dokumentasi Sandbox untuk opsi konfigurasi terperinci.

Perekaman

Terminal MCP dapat merekam sesi ke format asciicast v2, kompatibel dengan asciinema untuk pemutaran.

Mulai Cepat

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

Pemutaran

Pasang asciinema untuk memutar ulang rekaman:

# 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

Mode Perekaman

• always (default): Simpan setiap rekaman
• on-failure: Hanya simpan jika sesi keluar dengan kode non-nol (berguna untuk men-debug run CI yang gagal)

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

Perekaman Alat MCP

Asisten AI juga dapat mengontrol perekaman secara terprogram melalui alat MCP:

1. Panggil startRecording untuk mulai menangkap
2. Lakukan operasi terminal
3. Panggil stopRecording untuk finalisasi dan simpan

Ini memungkinkan alur kerja yang digerakkan AI seperti "rekam sesi debugging ini" atau "tangkap demo ini".

Arsitektur

Terminal MCP memiliki tiga mode operasi:

Mode	Bendera	Stdin	Deskripsi
Interaktif	(default)	TTY	Pengguna mendapatkan shell; AI terhubung melalui Unix socket
Klien	(default)	non-TTY	Terhubung ke socket sesi interaktif, melayani MCP melalui stdio
Headless	--headless	apa pun	Mandiri: PTY tertanam + server MCP melalui stdio

Mode headless (direkomendasikan untuk konfigurasi 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.)

Mode Interaktif + Klien (dua proses)

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)

Contoh Sesi

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

Pengembangan

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

Dokumentasi

Lihat folder docs untuk dokumentasi terperinci:

• Ringkasan
• Instalasi
• Referensi Alat
• Perekaman
• Konfigurasi
• Mode Sandbox
• Contoh
• Arsitektur

Persyaratan

• Node.js 18.0.0 atau lebih baru
• Windows 10 versi 1809 atau lebih baru (untuk dukungan ConPTY)

Lisensi

MIT