vscode-terminal-mcp

MCP-сервер, который выполняет команды в видимых вкладках терминала VSCode с полным захватом вывода. В отличие от встроенного выполнения, каждая команда запускается в реальном терминале, который вы можете видеть, прокручивать и с которым можете взаимодействовать.

Ключевые возможности

• Видимые терминалы: команды выполняются в реальных вкладках терминала VSCode, а не в скрытых процессах. Вы видите всё в реальном времени.

• Переиспользование сессий: инструмент run автоматически переиспользует простаивающие сессии, создавая новые терминалы только при необходимости.

• Поддержка длительных процессов: выполнение в фоновом режиме с waitForCompletion: false, затем опрос вывода с помощью read.

• Изоляция субагентов: помечайте сессии тегом agentId, чтобы изолировать параллельные рабочие нагрузки агентов.

Related MCP server: Terminal MCP

Требования

• VS Code 1.93+ (для Shell Integration API)

• Node.js 20+

Начало работы

Claude Code

claude mcp add BashTerm -- npx vscode-terminal-mcp@latest

VS Code / Copilot

Добавьте в ваш .vscode/mcp.json:

{
  "servers": {
    "BashTerm": {
      "type": "stdio",
      "command": "npx",
      "args": ["vscode-terminal-mcp@latest"]
    }
  }
}

Добавьте в ваш .cursor/mcp.json:

{
  "mcpServers": {
    "BashTerm": {
      "command": "npx",
      "args": ["-y", "vscode-terminal-mcp@latest"]
    }
  }
}

Добавьте в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "BashTerm": {
      "command": "npx",
      "args": ["-y", "vscode-terminal-mcp@latest"]
    }
  }
}

Ваш первый запрос

После установки попробуйте:

Выполни ls -la в терминале

Вы должны увидеть новую вкладку терминала в VSCode с выводом команды.

Скриншоты

Выполнение команды с помощью run

Диалог разрешения для exec

Результат exec с чистым выводом

Инструменты

Быстрое выполнение

Управление сессиями

Примеры использования

Простая команда

Инструмент run делает всё сам — создаёт терминал при необходимости, выполняет команду и возвращает чистый вывод:

> Run npm test

$ npm test
PASS src/utils.test.ts (3 tests)
PASS src/index.test.ts (5 tests)

[exit: 0 | 1243ms | session-abc123]

Длительный процесс

Для сборок, развёртываний или любых длительных команд:

> Start `npm run build` without waiting, then check progress

Агент будет:

1. Вызывать run с waitForCompletion: false — возвращается немедленно

2. Вызывать read с offset: -10, чтобы проверить последние 10 строк

3. Повторять, пока процесс не завершится

Интерактивные команды

Для команд, требующих ввода пользователя:

> Run npm init and answer the prompts

Агент будет:

1. Вызывать run с npm init

2. Вызывать read, чтобы увидеть подсказку

3. Вызывать input, чтобы отправить ответ

Параллельные агенты

Субагенты могут работать в изолированных терминалах с помощью agentId:

> Have one agent run tests while another runs the linter

Каждый субагент получает собственный терминал с тегом agentId, что предотвращает смешивание вывода.

Конфигурация

Расширение читает конфигурацию из настроек VSCode в разделе terminalMcp.*:

Рекомендуется: назначьте предпочтительным инструментом

LLM-агенты, такие как Claude Code, имеют встроенный инструмент Bash, который выполняет команды внутри чата. Вывод встраивается в разговор, и его трудно читать, особенно при объёмном выводе. Мы рекомендуем указать агенту предпочитать этот MCP вместо встроенного Bash.

Добавьте следующее в ваш CLAUDE.md (или аналогичный файл инструкций):

## Terminal Execution

Prefer the BashTerm MCP tools (`run`, `exec`, `read`, etc.) over the built-in Bash tool for executing commands.
BashTerm runs commands in visible VSCode terminal tabs where the user can see output in real time.
Only fall back to the built-in Bash tool for simple, non-interactive operations like reading environment variables.

For commands that may take longer than 30 seconds or produce large amounts of output (builds, test suites,
deployments, installs), use the pull mode pattern:
1. Call `run` with `waitForCompletion: false` to launch the command without blocking.
2. Call `read` with `offset: -10` to check the last 10 lines of output.
3. Repeat step 2 until you see the command has finished (look for exit messages, prompts, or "Done").
4. Report the final result to the user.

This prevents conversation timeouts and lets the user watch progress in the terminal in real time.

Почему это важно:

Разработка: обновление расширения

VSCode агрессивно кэширует расширения в памяти. При локальной разработке code --install-extension и даже "Developer: Reload Window" могут не перезагрузить ваши изменения. Используйте этот процесс:

Быстрое обновление (без перезапуска)

После изменения исходных файлов соберите и скопируйте напрямую в каталог установленного расширения:

cd /path/to/vscode-terminal-mcp
npm run build
cp dist/extension.js ~/.vscode/extensions/sirlordt.vscode-terminal-mcp-<version>/dist/extension.js

Затем выполните "Developer: Reload Window" (Ctrl+Shift+P).

Полная переустановка (если быстрое обновление не работает)

Если VSCode всё ещё использует старый код:

# 1. Uninstall and remove all copies
code --uninstall-extension sirlordt.vscode-terminal-mcp
rm -rf ~/.vscode/extensions/sirlordt.vscode-terminal-mcp-*

# 2. Check for ghost entries with old publisher names
# Look in ~/.vscode/extensions/extensions.json for stale entries
# Remove any entries with old publisher IDs (e.g., "terminal-mcp.vscode-terminal-mcp")

# 3. Close VSCode completely (not just reload)

# 4. Rebuild and install
npm run build
npx vsce package --allow-missing-repository
code --install-extension vscode-terminal-mcp-<version>.vsix --force

# 5. Open VSCode

Проверка загруженной версии

# Check which extension directories exist
ls ~/.vscode/extensions/ | grep terminal

# Verify your changes are in the installed extension
grep "YOUR_UNIQUE_STRING" ~/.vscode/extensions/sirlordt.vscode-terminal-mcp-*/dist/extension.js

# Compare checksums
md5sum dist/extension.js ~/.vscode/extensions/sirlordt.vscode-terminal-mcp-*/dist/extension.js

Обработка большого вывода

Когда read возвращает вывод, превышающий лимит токенов MCP-клиента, система автоматически сохраняет полный вывод во временный JSON-файл и возвращает путь к файлу в сообщении об ошибке.

Чтобы извлечь нужное содержимое:

# Get the last 50 lines (most relevant for status)
tail -50 /path/to/saved/file.txt

# Or parse the JSON to extract the text content
python3 -c "import json; data=json.load(open('/path/to/file.txt')); print(data[0]['text'][-2000:])"

Формат файла — JSON: [{"type": "text", "text": "..."}]

Это часто происходит с командами, которые создают объёмный TUI-вывод (индикаторы прогресса, ANSI-escape-последовательности). Используйте меньшие значения offset (например, offset: -20 вместо offset: -100), чтобы уменьшить размер захватываемого вывода.

Как это работает

1. Расширение VSCode активируется и запускает IPC-сервер на Unix-сокете

2. Точка входа MCP (mcp.js) запускается MCP-клиентом и связывает JSON-RPC stdio с IPC-сокетом

3. Команды выполняются в реальных терминалах VSCode с использованием Shell Integration API для надёжного захвата вывода и определения кода завершения

4. Вывод хранится в кольцевых буферах с поддержкой постраничного просмотра для эффективного чтения

Последние изменения (0.1.6)

• Скриншоты в README для маркетплейса

• Чистый формат вывода для всех инструментов — больше никакого сырого JSON

• Исправлено: waitForCompletion: false не работал

• Отключён сборщик простаивающих сессий — пользователь закрывает сессии вручную

• Уникальный IPC-сокет для каждой рабочей области (поддержка нескольких экземпляров)

• Пользовательские имена вкладок терминала с форматом даты

• Документация по обработке большого вывода

Полную историю изменений см. в CHANGELOG.md.

Лицензия

MIT