Terminal MCP

AI को अपने टर्मिनल को देखने और उसके साथ इंटरैक्ट करने दें।

Terminal MCP LLMs को आपके टर्मिनल सत्र का साझा दृश्य देता है। CLI और TUI अनुप्रयोगों को वास्तविक समय में डीबग करने के लिए, या AI को टर्मिनल-आधारित उपकरणों को स्वायत्त रूप से चलाने देने के लिए एकदम सही।

इंस्टॉल करें

npm install -g @ellery/terminal-mcp

या इंस्टॉल स्क्रिप्ट के माध्यम से:

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

अपने AI टूल कॉन्फ़िगर करें

अपनी मशीन पर स्थापित हर AI टूल के MCP कॉन्फ़िग में terminal-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.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 को फिर से चलाना एक no-op है।

अपग्रेड करना

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

इंटरैक्टिव मोड अगले लॉन्च पर एक बैनर प्रिंट करेगा जब कोई नया रिलीज़ उपलब्ध होगा — terminal-mcp दिन में एक बार npm रजिस्ट्री की जाँच करता है और परिणाम कैश करता है। हेडलेस और MCP-क्लाइंट मोड कभी जाँच या प्रिंट नहीं करते (इसलिए MCP stdio साफ रहता है)। पूरी तरह से ऑप्ट आउट करने के लिए, NO_UPDATE_NOTIFIER=1 सेट करें या --no-update-notifier पास करें।

विशेषताएँ

• पूर्ण टर्मिनल एमुलेशन: सटीक VT100/ANSI एमुलेशन के लिए xterm.js हेडलेस का उपयोग करता है
• क्रॉस-प्लेटफ़ॉर्म PTY: node-pty के माध्यम से मूल pseudo-terminal समर्थन (macOS, Linux, Windows)
• MCP प्रोटोकॉल: AI सहायक एकीकरण के लिए Model Context Protocol लागू करता है
• सत्र रिकॉर्डिंग: asciinema के साथ प्लेबैक के लिए टर्मिनल सत्रों को asciicast प्रारूप में रिकॉर्ड करें
• सरल API: इनपुट, अवलोकन, रिकॉर्डिंग और सत्र जीवनचक्र को कवर करने वाले नौ उपकरण
• हेडलेस मोड: TTY के बिना एक स्टैंडअलोन MCP सर्वर के रूप में चलाएं — 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 सॉकेट बनाता है), फिर आपका MCP क्लाइंट एक दूसरा उदाहरण बनाता है जो उस सॉकेट से जुड़ता है। इसके लिए TTY की आवश्यकता होती है।

हेडलेस मोड (--headless) एक एम्बेडेड PTY को आंतरिक रूप से बनाकर और एक ही प्रक्रिया में stdio पर सीधे MCP की सेवा करके इस आवश्यकता को समाप्त करता है। कोई इंटरैक्टिव टर्मिनल सत्र नहीं, कोई सॉकेट नहीं — बस एक अंतर्निहित टर्मिनल के साथ एक स्व-निहित MCP सर्वर।

हेडलेस मोड का उपयोग कब करें

• CI/CD पाइपलाइन — कोई TTY उपलब्ध नहीं
• Docker कंटेनर — साथ चलाने के लिए कोई इंटरैक्टिव शेल नहीं
• रिमोट/क्लाउड वातावरण — स्वचालन द्वारा बनाए गए MCP सर्वर
• सरलीकृत सेटअप — एकल प्रक्रिया, कोई सॉकेट समन्वय की आवश्यकता नहीं

कॉन्फ़िगरेशन

{
  "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
ansi	सामग्री फ़ील्ड में ANSI रंग escape कोड संरक्षित के साथ JSON
png	PNG छवि के रूप में रंगीन स्क्रीनशॉट (@resvg/resvg-js की आवश्यकता है)

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

ansi प्रारूप टर्मिनल के सेल बफर से SGR escape अनुक्रमों का पुनर्निर्माण करता है, 16-रंग, 256-रंग और 24-बिट truecolor विशेषताओं के साथ-साथ बोल्ड, डिम, इटैलिक और रेखांकित शैलियों को संरक्षित करता है।

png प्रारूप base64-एन्कोडेड PNG डेटा के साथ एक MCP image सामग्री ब्लॉक लौटाता है, जो 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 के बिना हर टूल कॉल एक एकल स्वतः-निर्मित डिफ़ॉल्ट सत्र को लक्षित करता है — वही व्यवहार जो प्रोजेक्ट में हमेशा रहा है। एक प्रक्रिया से कई पृथक PTY चलाने के लिए sessionId पास करें।

• डिफ़ॉल्ट सत्र पहले उपयोग पर बनाया जाता है और इसे नष्ट नहीं किया जा सकता।
• अतिरिक्त सत्र createSession द्वारा बनाए जाते हैं और तब तक ट्रैक किए जाते हैं जब तक वे नष्ट नहीं हो जाते या निष्क्रिय-निष्कासित नहीं हो जाते (--session-idle-timeout, डिफ़ॉल्ट 600s)।
• समवर्ती सत्र --max-sessions (डिफ़ॉल्ट 5) पर सीमित हैं।
• एक सक्रिय रिकॉर्डिंग प्रक्रिया में सभी सत्रों से आउटपुट कैप्चर करती है।

विशिष्ट उपयोग मामला: एक AI एजेंट एक सत्र में लंबे समय तक चलने वाले बिल्ड को चलाता है जबकि दूसरे में डायग्नोस्टिक्स चलाता है, बिना कमांड इंटरलीविंग के।

सैंडबॉक्स मोड

प्रतिबंधित फ़ाइलसिस्टम और नेटवर्क एक्सेस के साथ टर्मिनल चलाएं:

# 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: सुंदर फ़ॉलबैक (सैंडबॉक्स के बिना चलता है)

विस्तृत कॉन्फ़िगरेशन विकल्पों के लिए सैंडबॉक्स दस्तावेज़ीकरण देखें।

रिकॉर्डिंग

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 के तीन ऑपरेटिंग मोड हैं:

मोड	फ़्लैग	स्टडिन	विवरण
इंटरैक्टिव	(डिफ़ॉल्ट)	TTY	उपयोगकर्ता को एक शेल मिलता है; AI Unix सॉकेट के माध्यम से जुड़ता है
क्लाइंट	(डिफ़ॉल्ट)	गैर-TTY	एक इंटरैक्टिव सत्र के सॉकेट से जुड़ता है, 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