TermSSH MCP

✨ Почему TermSSH MCP

Большинство инструментов SSH для ИИ-рабочих процессов построены по принципу выполнить команду → получить вывод → готово.

Это не работает, когда реальная задача требует интерактивности:

• установщики задают вопросы

• оболочки (shells) сохраняют состояние

• отладка требует нескольких шагов

• развертывание требует загрузки файлов и управления терминалом

• агентам нужно наблюдать, реагировать и продолжать работу

TermSSH MCP создан для решения этой проблемы.

Вместо того чтобы притворяться, что всё является одной командой, он предоставляет MCP-клиентам настоящий рабочий процесс в стиле оператора:

открыть оболочку → ввести данные → прочитать вывод → сохранить контекст → загрузить файлы → продолжить работу

🧠 Что его отличает

Приоритет терминала

Интерактивные терминальные сессии являются основной моделью, а не второстепенной функцией.

Готовность к работе с агентами

Разработан для MCP-клиентов, ИИ-агентов для написания кода и циклов автоматизации.

Рабочие процессы с сохранением состояния

Повторное использование активных сессий делает многошаговые задачи естественными и надежными.

Загрузка включена

Перемещайте скрипты, конфигурации, полезные нагрузки и созданные артефакты через SFTP.

Кроссплатформенность

Работает с SSH-целями на Linux и Windows.

Чистый набор инструментов

Специализированные MCP-инструменты для управления терминалом и удаленной доставки файлов.

🚀 Основные возможности

• Интерактивные SSH-терминальные сессии

• Инкрементальный поток чтения/записи терминала

• Управляемое повторное использование терминальных сессий по умолчанию

• Опциональное принудительное создание нескольких сессий

• Локальная загрузка файлов через SFTP

• Прямая загрузка текста и контента в формате base64

• Поддержка изменения размера терминала

• Поддержка SSH-целей на Linux и Windows

• MCP-родной интерфейс для ИИ-инструментов

🧰 Набор инструментов

upload-file

Загрузка локального файла с хоста MCP на удаленный SSH-сервер с использованием SFTP.

Параметры

• localPath — путь к локальному исходному файлу

• remotePath — путь назначения на удаленном хосте

• createDirectories — создавать отсутствующие родительские каталоги при необходимости

• overwrite — перезаписать существующий удаленный файл, если он есть

• mode — опциональный POSIX-режим, например 0644

upload-content

Загрузка прямого текста или контента в формате base64 на удаленный сервер.

Параметры

• content — необработанный текст или полезная нагрузка base64

• encoding — utf8 или base64

• remotePath — путь назначения на удаленном хосте

• createDirectories — создавать отсутствующие родительские каталоги при необходимости

• overwrite — перезаписать существующий удаленный файл, если он есть

• mode — опциональный POSIX-режим, например 0644

terminal-start

Запуск интерактивной удаленной терминальной сессии.

Параметры

• cwd — опциональный рабочий каталог после запуска оболочки

• shell — опциональный бинарный файл оболочки

• platformHint — auto, linux или windows

• elevated — попытка повышения прав через su при настройке

• cols — ширина терминала

• rows — высота терминала

• env — опциональные переменные окружения

• multiSession — установите true, чтобы принудительно создать новую управляемую сессию вместо повторного использования существующей

terminal-write

Запись ввода в активную терминальную сессию.

Параметры

• sessionId — идентификатор целевой сессии

• input — текст для отправки

• appendNewline — автоматически добавлять символ новой строки при необходимости

terminal-read

Чтение буферизованного вывода из терминальной сессии.

Параметры

• sessionId — идентификатор целевой сессии

• sinceSequence — возвращать только вывод, который новее указанного порядкового номера

• maxChars — ограничить размер возвращаемого вывода

• waitForMs — опциональная короткая задержка опроса

terminal-resize

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

Параметры

• sessionId — идентификатор целевой сессии

• cols — новая ширина

• rows — новая высота

terminal-close

Закрытие терминальной сессии локально.

Параметры

• sessionId — идентификатор целевой сессии

🔄 Типичный рабочий процесс

flowchart LR
    A[terminal-start] --> B[terminal-write]
    B --> C[terminal-read]
    C --> D{Need file?}
    D -- Yes --> E[upload-file / upload-content]
    D -- No --> F{Continue session?}
    E --> F
    F -- Yes --> B
    F -- No --> G[terminal-close]

Это особенно хорошо подходит для:

• интерактивной установки пакетов

• удаленной настройки и подготовки

• развертывания с загрузкой артефактов

• отладки сервисов в несколько шагов

• рабочих процессов в оболочке с сохранением состояния, где важен контекст

🛠 Установка

Клонирование репозитория

git clone https://github.com/rayss868/termssh-mcp.git
cd termssh-mcp
npm install
npm run build

Глобальная установка

npm install -g termssh-mcp

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

Обязательные параметры CLI

• host — имя хоста или IP-адрес удаленной машины

• user — имя пользователя SSH

Опциональные параметры CLI

• port — SSH-порт, по умолчанию 22

• password — пароль SSH

• key — путь к приватному SSH-ключу

• sudoPassword — опциональный пароль для рабочих процессов, ориентированных на sudo

• suPassword — опциональный пароль для повышения прав через su

• timeout — тайм-аут готовности SSH в миллисекундах, по умолчанию 60000

• maxChars — лимит проверки длины команды, по умолчанию 1000; используйте none или 0 для безлимитного режима

🧩 Пример конфигурации MCP

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=1.2.3.4",
        "--port=22",
        "--user=root",
        "--password=pass",
        "--timeout=30000",
        "--maxChars=none"
      ]
    }
  }
}

Пример с SSH-ключом

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=example.com",
        "--user=root",
        "--key=/path/to/private/key"
      ]
    }
  }
}

🤖 Пример Claude Code

Зарегистрируйте сервер в Claude Code:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=YOUR_HOST --user=YOUR_USER --password=YOUR_PASSWORD

С аутентификацией по SSH-ключу:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=example.com --user=root --key=/path/to/private/key

С увеличенным тайм-аутом:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=192.168.1.100 --user=admin --password=your_password --timeout=120000 --maxChars=none

🎯 Отлично подходит для

Разработчиков

• удаленный доступ к оболочке из ИИ-инструментов для кодинга

• сессии отладки с сохранением состояния

• доставка скриптов и конфигураций

DevOps / инфраструктурных команд

• инспекция сервисов

• поддержка развертывания

• многошаговые удаленные операции

Создателей агентов

• MCP-рабочие процессы с родным терминалом

• повторно используемые сессии

• контролируемые циклы удаленной автоматизации

🏗 Разработка

Сборка проекта:

npm run build

Запуск тестов:

npm test

Использование MCP Inspector:

npm run inspect

📁 Структура проекта

• src/index.ts — точка входа сервера MCP и регистрация инструментов

• src/ssh-connection-manager.ts — обработка SSH-соединения и жизненного цикла терминала

• src/upload.ts — вспомогательные функции для загрузки и метаданных интерактивной сессии

• src/core.ts — общие примитивы проверки и SSH-утилиты

• test/upload-and-terminal.test.ts — покрытие модульными тестами загрузки/сессии

• test/maxChars.test.ts — покрытие проверки команд

• test/smoke.ssh.test.ts — дымовые тесты для текущего экспортируемого поведения

🗺 Идеи для дорожной карты

• более богатая инспекция метаданных сессии

• лучшая наблюдаемость удаленных сессий

• опциональные функции сохранения сессий

• больше примеров для Claude Code и инструментов MCP

• шаблоны рабочих процессов, ориентированные на развертывание

🔐 Примечание по безопасности

TermSSH MCP предоставляет удаленный доступ к системам по SSH. Используйте его только для инфраструктуры, которой вы владеете или которой вам явно разрешено управлять.

📜 Лицензия

Выпущено под лицензией MIT.

🤝 Участие в разработке

Вклад приветствуется. См. CONTRIBUTING.md для руководства по внесению вклада и CODE_OF_CONDUCT.md для ожидаемого поведения.