Terminal MCP

Позвольте ИИ видеть и взаимодействовать с вашим терминалом.

Terminal MCP предоставляет LLM общий доступ к вашей терминальной сессии. Идеально подходит для отладки CLI и TUI-приложений в реальном времени, а также для автономного управления терминальными инструментами с помощью ИИ.

Установка

npm install -g @ellery/terminal-mcp

Или через установочный скрипт:

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

Настройка ваших ИИ-инструментов

Подключите terminal-mcp к 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 не вызывает изменений.

Обновление

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

Интерактивный режим выведет баннер при следующем запуске, когда доступна более новая версия — terminal-mcp проверяет npm-реестр один раз в день и кэширует результат. Безголовый режим и режим MCP-клиента никогда не проверяют и не выводят ничего (поэтому MCP stdio остается чистым). Чтобы полностью отказаться, установите NO_UPDATE_NOTIFIER=1 или передайте --no-update-notifier.

Возможности

• Полная эмуляция терминала: использует xterm.js headless для точной эмуляции VT100/ANSI
• Кроссплатформенный PTY: нативная поддержка псевдотерминалов через node-pty (macOS, Linux, Windows)
• Протокол MCP: реализует Model Context Protocol для интеграции с ИИ-ассистентами
• Запись сессий: запись терминальных сессий в формат asciicast для воспроизведения с помощью asciinema
• Простой API: девять инструментов, охватывающих ввод, наблюдение, запись и жизненный цикл сессий
• Безголовый режим: запуск как автономного MCP-сервера без TTY — идеально для 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 внутри и обслуживая MCP напрямую через stdio в одном процессе. Никакой интерактивной терминальной сессии, никакого сокета — просто автономный 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. Опустите его, чтобы нацелиться на сессию по умолчанию; передайте 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-escape-последовательности из буфера ячеек терминала, сохраняя атрибуты 16-цветной, 256-цветной и 24-битной truecolor палитры, а также жирный, тусклый, курсивный и подчеркнутый стили.

Формат png возвращает MCP-блок содержимого image с данными 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).
• Активная запись захватывает вывод всех сессий в процессе.

Типичный сценарий использования: ИИ-агент запускает длительную сборку в одной сессии, одновременно выполняя диагностику в другой, без перемешивания команд.

Режим песочницы

Запуск терминала с ограниченным доступом к файловой системе и сети:

# 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

ИИ-ассистенты также могут управлять записью программно через инструменты MCP:

1. Вызовите startRecording, чтобы начать захват
2. Выполните операции в терминале
3. Вызовите stopRecording, чтобы финализировать и сохранить

Это позволяет реализовать рабочие процессы на основе ИИ, такие как «запиши эту сессию отладки» или «захвати эту демонстрацию».

Архитектура

Terminal MCP имеет три режима работы:

Режим	Флаг	Stdin	Описание
Интерактивный	(по умолчанию)	TTY	Пользователь получает оболочку; ИИ подключается через Unix-сокет
Клиент	(по умолчанию)	non-TTY	Подключается к сокету интерактивной сессии, обслуживает MCP через stdio
Безголовый	--headless	любой	Автономный: встроенный PTY + MCP-сервер через stdio

Безголовый режим (рекомендуется для 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