Terminal MCP

Yapay zekanın terminalinizi görmesine ve onunla etkileşim kurmasına izin verin.

Terminal MCP, LLM'lere terminal oturumunuzun ortak bir görünümünü sunar. CLI ve TUI uygulamalarını gerçek zamanlı olarak hata ayıklamak veya yapay zekanın terminal tabanlı araçları otonom olarak kullanmasını sağlamak için mükemmeldir.

Kurulum

npm install -g @ellery/terminal-mcp

Veya kurulum betiği ile:

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

Yapay zeka araçlarınızı yapılandırın

terminal-mcp öğesini makinenizde kurulu her yapay zeka aracının MCP yapılandırmasına tek seferde bağlayı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

Desteklenen istemciler (her biri kendi yapılandırma biçimi için doğru şemayı alır):

İstemci	Yapılandırma dosyası	Biçim
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

İlk kurulumda, mevcut herhangi bir yapılandırmanın .bak orijinalin yanına yazılır. terminal-mcp girdisi, diğer sunuculara veya ilgisiz anahtarlara dokunmadan eklenir; setup komutunu tekrar çalıştırmak hiçbir işlem yapmaz.

Yükseltme

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

Etkileşimli mod, daha yeni bir sürüm mevcut olduğunda bir sonraki başlatmada bir bildirim yazdırır — terminal-mcp npm kayıt defterini günde bir kez kontrol eder ve sonucu önbelleğe alır. Başsız ve MCP istemci modları asla kontrol etmez veya hiçbir şey yazdırmaz (böylece MCP stdio temiz kalır). Tamamen devre dışı bırakmak için NO_UPDATE_NOTIFIER=1 ayarlayın veya --no-update-notifier parametresini geçirin.

Özellikler

• Tam Terminal Emülasyonu: Doğru VT100/ANSI emülasyonu için başsız xterm.js kullanır
• Platformlar Arası PTY: node-pty aracılığıyla yerel sözde terminal desteği (macOS, Linux, Windows)
• MCP Protokolü: Yapay zeka asistanı entegrasyonu için Model Context Protocol uygular
• Oturum Kaydı: asciinema ile oynatma için terminal oturumlarını asciicast biçiminde kaydeder
• Basit API: Giriş, gözlem, kayıt ve oturum yaşam döngüsünü kapsayan dokuz araç
• Başsız Mod: TTY olmadan bağımsız bir MCP sunucusu olarak çalışır — CI, konteynerler ve etkileşimli olmayan ortamlar için idealdir
• Çoklu Oturum: Tek bir süreçte sessionId ile adreslenen birden çok izole terminal oturumu çalıştırın
• Korumalı Alan Modu: Dosya sistemi ve ağ erişimi için isteğe bağlı güvenlik kısıtlamaları

Kaynaktan Derleme

npm install
npm run build

Kullanım

MCP Yapılandırması

MCP istemci ayarlarınıza ekleyin:

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

Özel seçeneklerle:

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

Komut Satırı Seçenekleri

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)

Başsız Mod

Varsayılan olarak, Terminal MCP çift süreçli bir mimari kullanır: terminal-mcp komutunu etkileşimli bir terminalde çalıştırırsınız (bir Unix soketi oluşturur), ardından MCP istemciniz bu sokete bağlanan ikinci bir örnek başlatır. Bu bir TTY gerektirir.

Başsız mod (--headless), dahili olarak gömülü bir PTY başlatarak ve MCP'yi tek bir süreçte doğrudan stdio üzerinden sunarak bu gereksinimi ortadan kaldırır. Etkileşimli terminal oturumu yok, soket yok — yalnızca yerleşik terminale sahip, kendi kendine yeten bir MCP sunucusu.

Başsız mod ne zaman kullanılır

• CI/CD boru hatları — TTY yok
• Docker konteynerleri — birlikte çalıştırılacak etkileşimli kabuk yok
• Uzak/bulut ortamları — otomasyonla başlatılan MCP sunucuları
• Basitleştirilmiş kurulum — tek süreç, soket koordinasyonu gerekmez

Yapılandırma

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

Nasıl çalışır

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

Başsız modda, terminal oturumu başlangıçta hemen başlatılır, böylece tüm araçlar (type, sendKey, getContent, takeScreenshot, startRecording, stopRecording, createSession, listSessions, destroySession) anında kullanılabilir.

MCP Araçları

Tüm giriş/çıkış araçları (type, sendKey, getContent, takeScreenshot) isteğe bağlı bir sessionId bağımsız değişkenini kabul eder. Varsayılan oturumu hedeflemek için bunu atlayın; belirli bir oturumu sürmek için createSession tarafından döndürülen kimliği geçirin.

type

Terminale metin girişi gönderin.

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

sendKey

Özel tuşlar veya tuş kombinasyonları gönderin.

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

Desteklenen tuşlar:

• Temel: Enter, Tab, Escape, Backspace, Delete
• Ok: ArrowUp, ArrowDown, ArrowLeft, ArrowRight
• Gezinme: Home, End, PageUp, PageDown, Insert
• İşlev: F1 ile F12 arası
• Kontrol: Ctrl+A ile Ctrl+Z arası, Ctrl+C, Ctrl+D, vb.

getContent

Terminal arabelleğini düz metin olarak alın.

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

takeScreenshot

Terminal durumunu yakalayın. Üç çıkış biçimini destekler:

Biçim	Açıklama
text (varsayılan)	Düz metin içeriği, imleç konumu ve boyutları içeren JSON
ansi	İçerik alanında ANSI renk kaçış kodları korunmuş JSON
png	PNG görüntüsü olarak renkli ekran görüntüsü (@resvg/resvg-js gerektirir)

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

ansi biçimi, terminalin hücre arabelleğinden SGR kaçış dizilerini yeniden oluşturur; kalın, soluk, italik ve altı çizili stillerle birlikte 16 renk, 256 renk ve 24 bit gerçek renk özniteliklerini korur.

png biçimi, One Dark renk teması ve macOS tarzı pencere çerçevesiyle işlenmiş, base64 kodlu PNG verileri içeren bir MCP image içerik bloğu döndürür.

startRecording

Terminal çıktısını bir asciicast v2 dosyasına kaydetmeye başlayın.

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

Seçenekler:

• mode: always (tümünü kaydet) veya on-failure (yalnızca sıfır olmayan çıkışta kaydet)
• outputDir: Özel çıktı dizini
• idleTimeLimit: Olaylar arasındaki maksimum saniye (oynatmada duraklamaları sınırlar)
• maxDuration: N saniye sonra otomatik durdur
• inactivityTimeout: N saniye çıktı olmadan sonra otomatik durdur

stopRecording

Bir kaydı durdurun ve asciicast dosyasını sonlandırın.

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

createSession

Yeni bir terminal oturumu oluşturun ve meta verilerini döndürün. Sonraki araç çağrılarında bu oturumu hedeflemek için döndürülen sessionId değerini kullanın.

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

Tüm bağımsız değişkenler isteğe bağlıdır. Döndürür:

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

Varsayılan dahil tüm etkin oturumları listeleyin. Yapılandırılmış sınırları bildirir.

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

destroySession

Bir oturumu kimliğe göre yok edin. Varsayılan oturum yok edilemez.

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

Çoklu Oturum

Varsayılan olarak, sessionId olmadan yapılan her araç çağrısı, otomatik oluşturulan tek bir varsayılan oturumu hedefler — projenin her zaman sahip olduğu davranışın aynısı. Tek bir süreçten birden çok izole PTY sürmek için sessionId değerini geçirin.

• Varsayılan oturum ilk kullanımda oluşturulur ve yok edilemez.
• Ek oturumlar createSession tarafından oluşturulur ve yok edilene veya boşta kalma nedeniyle çıkarılana kadar izlenir (--session-idle-timeout, varsayılan 600s).
• Eşzamanlı oturumlar --max-sessions ile sınırlandırılmıştır (varsayılan 5).
• Etkin bir kayıt, süreçteki tüm oturumlardan çıktıyı yakalar.

Tipik kullanım durumu: bir yapay zeka aracısının bir oturumda uzun süren bir derlemeyi sürerken diğerinde tanılama çalıştırması, komut karışması olmadan.

Korumalı Alan Modu

Terminali kısıtlı dosya sistemi ve ağ erişimiyle çalıştırın:

# Interactive permission configuration
terminal-mcp --sandbox

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

Etkileşimli mod, izinleri yapılandırmak için bir TUI iletişim kutusu gösterir:

- **Okuma/Yazma**: Tam erişim (geçerli dizin, /tmp, önbellekler) - **Salt Okunur**: Okuyabilir ancak değiştiremez (ev dizini) - **Engellendi**: Erişim yok (SSH anahtarları, bulut kimlik bilgileri, kimlik doğrulama belirteçleri)

Örnek yapılandırma dosyası:

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

Platform desteği:

• macOS: sandbox-exec (Seatbelt) aracılığıyla tam destek
• Linux: bubblewrap aracılığıyla tam destek (bwrap kurulu olması gerekir)
• Windows: Zarif geri dönüş (korumalı alan olmadan çalışır)

Ayrıntılı yapılandırma seçenekleri için Korumalı Alan Belgeleri bölümüne bakın.

Kayıt

Terminal MCP, oturumları asciinema ile oynatma için uyumlu asciicast v2 biçiminde kaydedebilir.

Hızlı Başlangıç

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

Oynatma

Kayıtları oynatmak için asciinema'yı kurun:

# 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

Kayıt Modları

• always (varsayılan): Her kaydı kaydet
• on-failure: Yalnızca oturum sıfır olmayan bir kodla çıkarsa kaydet (başarısız CI çalıştırmalarında hata ayıklamak için kullanışlıdır)

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

MCP Aracı Kaydı

Yapay zeka asistanları, MCP araçları aracılığıyla kaydı programlı olarak da kontrol edebilir:

1. Yakalamaya başlamak için startRecording çağırın
2. Terminal işlemlerini gerçekleştirin
3. Sonlandırmak ve kaydetmek için stopRecording çağırın

Bu, "bu hata ayıklama oturumunu kaydet" veya "bu demoyu yakala" gibi yapay zeka odaklı iş akışlarını etkinleştirir.

Mimari

Terminal MCP'nin üç çalışma modu vardır:

Mod	Bayrak	Stdin	Açıklama
Etkileşimli	(varsayılan)	TTY	Kullanıcı bir kabuk alır; yapay zeka Unix soketi üzerinden bağlanır
İstemci	(varsayılan)	TTY olmayan	Etkileşimli oturumun soketine bağlanır, MCP'yi stdio üzerinden sunar
Başsız	--headless	herhangi	Kendi kendine yeten: gömülü PTY + stdio üzerinden MCP sunucusu

Başsız mod (MCP yapılandırmaları için önerilir)

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

Etkileşimli + İstemci modu (çift süreç)

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)

Örnek Oturum

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

Geliştirme

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

Belgeler

Ayrıntılı belgeler için docs klasörüne bakın:

• Genel Bakış
• Kurulum
• Araçlar Referansı
• Kayıt
• Yapılandırma
• Korumalı Alan Modu
• Örnekler
• Mimari

Gereksinimler

• Node.js 18.0.0 veya sonrası
• Windows 10 sürüm 1809 veya sonrası (ConPTY desteği için)

Lisans

MIT