mcp-ssh-tool

Сервер SSH-клиента на базе протокола Model Context Protocol (MCP), обеспечивающий автономные SSH-операции для GitHub Copilot и VS Code. Включите автоматизацию SSH на естественном языке без ручных запросов или взаимодействия с графическим интерфейсом.

Официальная запись в реестре MCP: io.github.oaslananka/mcp-ssh-tool
Метаданные реестра: https://registry.modelcontextprotocol.io/v0.1/servers/io.github.oaslananka%2Fmcp-ssh-tool/versions/latest

Быстрый старт

Установка

• Глобальная установка (рекомендуется): npm install -g mcp-ssh-tool

• Разовый запуск: npx mcp-ssh-tool

Конфигурация MCP-клиента (VS Code / Claude Desktop / другие)

Добавьте в вашу конфигурацию MCP (mcp.json, .vscode/mcp.json или конфигурацию Claude Desktop MCP):

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

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

После настройки вы можете использовать естественный язык в своем MCP-клиенте:

• SSH-соединение: "Connect to server 192.168.1.100 as admin using SSH key"

• Операции с файлами: "Read the content of /etc/nginx/nginx.conf on the server"

• Выполнение команд: "Run 'systemctl status nginx' on the remote server"

• Управление пакетами: "Install htop package on Ubuntu server"

• Управление службами: "Restart the nginx service"

• Claude Desktop: "connect to my server and check disk usage"

• Установка пакета/стека служб: "install nginx on my remote server"

• Чтение файла конфигурации: "read the file /etc/nginx/nginx.conf"

• Перезапуск службы: "restart the nginx service"

• Просмотр логов: "list files in /var/log"

Доступные инструменты

• ssh_open_session — Установление SSH-соединения с различными методами аутентификации

• ssh_close_session — Закрытие SSH-сессии

• ssh_list_sessions — Список всех активных SSH-сессий

• ssh_ping — Проверка активности и отклика сессии

• ssh_list_configured_hosts — Список хостов из ~/.ssh/config

• ssh_resolve_host — Разрешение псевдонима хоста из SSH-конфигурации

• proc_exec — Удаленное выполнение команд (с опциональным таймаутом)

• proc_sudo — Выполнение команд с привилегиями sudo

• fs_read, fs_write, fs_list, fs_stat, fs_mkdirp, fs_rmrf, fs_rename — Операции с файловой системой

• ensure_package — Управление пакетами с состояниями present и absent

• ensure_service — Управление службами, включая restarted

• ensure_lines_in_file — Управление строками в файлах с состояниями present и absent

• patch_apply — Применение патчей к файлам

• os_detect — Определение информации о системе

• get_metrics — Метрики сервера в формате JSON или Prometheus

• proc_exec_stream — Потоковое выполнение команд с выводом по частям

• file_upload, file_download — Вспомогательные инструменты для передачи файлов по SFTP

• tunnel_local_forward, tunnel_remote_forward, tunnel_close, tunnel_list — Управление туннелями

Доступные ресурсы

• mcp-ssh-tool://sessions/active — Активные сессии в формате JSON

• mcp-ssh-tool://metrics/json — Снимок метрик в формате JSON

• mcp-ssh-tool://metrics/prometheus — Экспорт метрик в формате Prometheus

• mcp-ssh-tool://ssh-config/hosts — Разобранные локальные псевдонимы SSH-хостов

Обзор

SSH MCP-сервер выступает в качестве моста между GitHub Copilot и удаленными системами через SSH. Он поддерживает:

• Неинтерактивные SSH-операции — Никаких запросов или взаимодействия с GUI

• Множественные методы аутентификации — Пароль, SSH-ключи или SSH-агент

• Управление сессиями — Автоматическое объединение соединений в пул с TTL и вытеснением по алгоритму LRU

• Операции с файловой системой — Чтение, запись, список и управление удаленными файлами через SFTP, с резервным использованием SSH-оболочки для хостов, не предоставляющих подсистему SFTP

• Выполнение процессов — Удаленный запуск команд и операций sudo

• Автоматизация высокого уровня — Управление пакетами, службами и конфигурациями

• Безопасность — Автоматическое скрытие конфиденциальных данных в логах

Архитектура

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  GitHub Copilot │────│  SSH MCP Server  │────│  Remote Systems │
│     / VS Code   │    │                  │    │   (via SSH)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │ MCP stdio protocol    │ Session management    │ SSH + optional SFTP
         │                       │ LRU cache + TTL       │
         │                       │ Auth strategies       │

Встраиваемые / BusyBox цели

Некоторые встраиваемые системы предоставляют выполнение SSH-команд, но не имеют подсистемы SFTP, что часто встречается в системах на базе Dropbear или BusyBox. В этом случае ssh_open_session все равно выполняется успешно и сообщает sftpAvailable: false. Основные файловые инструменты, такие как fs_read, fs_write, fs_stat, fs_list, fs_mkdirp, fs_rmrf и fs_rename, автоматически переключаются на реализацию через оболочку (shell).

Установка

Предварительные требования

• Node.js ≥ 20 (LTS)

• SSH-доступ к целевым системам

• SSH-ключи или учетные данные для аутентификации

Установка из npm

npm install -g mcp-ssh-tool

Сборка из исходного кода

git clone https://github.com/oaslananka/mcp-ssh-tool.git
cd mcp-ssh-tool
npm install
npm run build
npm link

Флаги CLI

• --help / -h: Показать использование и примеры.

• --version / -v: Вывести версию.

• --stdio: Принудительный режим stdio (по умолчанию).

Примечание: Это MCP-сервер, работающий через stdio. Терминал не является интерактивной оболочкой; используйте MCP-клиент (Claude Desktop, VS Code MCP и т.д.) или отправляйте JSON-RPC через stdio.

Примечания по платформам

• Linux / macOS: Использует POSIX-оболочки с безопасным экранированием. Временная директория по умолчанию: /tmp.

• Цели Windows: Требуется сервер/агент OpenSSH; поиск ключей проверяет C:\Users\<you>\.ssh\. Команды упаковываются для безопасного выполнения в PowerShell. Вспомогательные инструменты для пакетов/служб намеренно отключены для целей Windows.

• Хост-ключи: Проверка хост-ключей по умолчанию ослаблена. Установите STRICT_HOST_KEY_CHECKING=true и, опционально, KNOWN_HOSTS_PATH для принудительной проверки.

Интеграция с ChatGPT Desktop

Быстрая настройка

npm run setup:chatgpt

Эта команда автоматически настраивает ChatGPT Desktop для использования mcp-ssh-tool.

Ручная настройка

Добавьте в конфигурацию ChatGPT Desktop MCP:

• macOS: ~/Library/Application Support/ChatGPT/mcp.json

• Windows: %APPDATA%\ChatGPT\mcp.json

• Linux: ~/.config/chatgpt/mcp.json

{
  "mcpServers": {
    "ssh-mcp-server": {
      "name": "ssh-mcp-server",
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

Для получения подробной информации см. docs/chatgpt-usage.md.

Интеграция с Codex

Быстрая настройка

Установите пакет глобально, затем зарегистрируйте его в Codex:

npm install -g mcp-ssh-tool
codex mcp add ssh-mcp -- mcp-ssh-tool

Если вы предпочитаете не устанавливать глобально, вы можете зарегистрировать его через npx:

codex mcp add ssh-mcp -- npx -y mcp-ssh-tool

Проверка

Убедитесь, что Codex видит MCP-сервер:

codex mcp list
codex mcp get ssh-mcp

Вы должны увидеть включенный stdio-сервер, чья команда — mcp-ssh-tool или npx.

Опциональное усиление безопасности

Чтобы принудительно включить проверку хост-ключей в процессе сервера, управляемом Codex:

codex mcp remove ssh-mcp
codex mcp add ssh-mcp \
  --env STRICT_HOST_KEY_CHECKING=true \
  --env KNOWN_HOSTS_PATH=/path/to/known_hosts \
  -- mcp-ssh-tool

После добавления сервера перезапустите Codex или откройте новую сессию, затем попробуйте вызвать простой инструмент, например, список активных сессий или открытие SSH-соединения.

Интеграция с VS Code Copilot

Конфигурация на уровне пользователя (рекомендуется)

Откройте VS Code и нажмите Ctrl+Shift+P, затем выполните "MCP: Open User Configuration".

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

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

Конфигурация на уровне рабочей области

Создайте .vscode/mcp.json в вашей рабочей области:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

Проверка

1. Перезапустите VS Code

2. Откройте Copilot Chat

3. Инструменты SSH MCP должны появиться в списке доступных инструментов

4. Протестируйте с помощью: "Connect to 192.168.1.100 as admin and run 'uname -a'"

Claude Desktop, Antigravity и другие MCP-клиенты

Любой MCP-совместимый клиент, который может запустить stdio-сервер, может использовать mcp-ssh-tool. Точный экран настроек или файл конфигурации зависит от клиента, но процесс везде одинаков:

1. Установите пакет:

npm install -g mcp-ssh-tool

2. Зарегистрируйте stdio MCP-сервер, который запускает:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

3. Если клиент использует схему типа mcpServers вместо servers, используйте эквивалентную запись:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

Для Claude Desktop используйте тот же шаблон команды stdio, что и выше, в его конфигурации MCP. Для Antigravity или других MCP-клиентов используйте собственный интерфейс настроек MCP или формат конфигурации клиента, но укажите в нем ту же исполняемую команду.

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

Базовое соединение и выполнение команд

"Connect to 10.11.12.13 as deployer with password 'mypass' and run 'df -h'"

Операции с файлами

"Connect to server.example.com as admin, read /etc/nginx/nginx.conf and show me the server blocks"

Системное администрирование

"Connect to 192.168.1.50 as root, install htop package, start nginx service, and list /var/www contents"

Управление конфигурацией

"Connect to web-server as admin, add these lines to /etc/hosts:
192.168.1.10 db-server
192.168.1.20 cache-server
Then restart networking service"

Готовые идеи для промптов

"connect to my server and check disk usage"

"install nginx on my remote server"

"read the file /etc/nginx/nginx.conf"

"restart the nginx service"

"list files in /var/log"

Советы профессионалов

• Множественные сессии: Открывайте по одной сессии на хост или окружение и поддерживайте их активность с помощью ssh_list_sessions и ssh_ping, когда переключаетесь между производственными, тестовыми и рабочими машинами.

• Резервный SFTP для BusyBox/Dropbear: На встраиваемых системах, которые не предоставляют подсистему SFTP, ssh_open_session все равно может завершиться успешно с sftpAvailable: false, и основные инструменты fs_* автоматически переключатся на реализацию через оболочку.

• Проверка хост-ключей: Установите STRICT_HOST_KEY_CHECKING=true в окружении MCP-сервера и, опционально, KNOWN_HOSTS_PATH для более строгой проверки SSH промышленного уровня.

Справочник API

Архитектура

src/
├── container.ts       - Dependency injection wiring
├── config.ts          - ConfigManager (env + programmatic overrides)
├── index.ts           - CLI entry point & graceful shutdown
├── mcp.ts             - MCP server (thin: delegates to ToolRegistry)
├── tools/
│   ├── registry.ts    - ToolRegistry (routes CallTool requests)
│   ├── types.ts       - ToolProvider interface
│   ├── session.provider.ts
│   ├── process.provider.ts
│   ├── fs.provider.ts
│   ├── ensure.provider.ts
│   ├── system.provider.ts
│   ├── transfer.provider.ts
│   └── tunnel.provider.ts
├── session.ts         - SessionManager (LRU cache + TTL)
├── resources.ts       - MCP resources for sessions, metrics, and SSH hosts
├── telemetry.ts       - Optional OpenTelemetry tracing
├── rate-limiter.ts    - Sliding window rate limiter
├── metrics.ts         - Prometheus-compatible metrics
├── safety.ts          - Command safety warnings (non-blocking)
└── ...                - fs-tools, process, ensure, detect, ...

Добавление новой группы инструментов

1. Создайте src/tools/<your-namespace>.provider.ts, реализующий ToolProvider

2. Зарегистрируйте его в src/tools/index.ts

3. Добавьте модульные тесты в test/unit/tools/<your-namespace>.provider.test.ts

Изменения в mcp.ts не требуются.

Инструменты сессий

ssh_open_session

{
  "host": "example.com",
  "username": "admin",
  "port": 22,
  "auth": "auto",
  "password": "optional",
  "privateKey": "optional-inline-key",
  "privateKeyPath": "optional-path",
  "passphrase": "optional",
  "useAgent": false,
  "readyTimeoutMs": 20000,
  "ttlMs": 900000
}

Возвращает:

{
  "sessionId": "ssh-1645123456789-1",
  "host": "example.com",
  "username": "admin",
  "expiresInMs": 900000
}

ssh_close_session

{
  "sessionId": "ssh-1645123456789-1"
}

ssh_list_sessions, ssh_ping, ssh_list_configured_hosts, ssh_resolve_host

• ssh_list_sessions возвращает активные сессии с оставшимся TTL.

• ssh_ping проверяет активность и задержку сессии.

• ssh_list_configured_hosts читает ~/.ssh/config.

• ssh_resolve_host разворачивает псевдоним SSH-хоста в параметры соединения.

Инструменты команд

proc_exec

{
  "sessionId": "ssh-1645123456789-1",
  "command": "ls -la /home",
  "cwd": "/tmp",
  "env": {
    "DEBUG": "1"
  },
  "timeoutMs": 30000
}

proc_sudo

{
  "sessionId": "ssh-1645123456789-1",
  "command": "systemctl restart nginx",
  "password": "sudo-password",
  "cwd": "/etc",
  "timeoutMs": 30000
}

Оба возвращают:

{
  "code": 0,
  "stdout": "command output",
  "stderr": "",
  "durationMs": 245
}

Файловые инструменты

• fs_read

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "encoding": "utf8"
}

• fs_write

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/tmp/config.txt",
  "data": "server_name example.com;\nlisten 80;",
  "mode": 420
}

• fs_stat возвращает size, mtime, mode и type.

• fs_list возвращает { "entries": [...], "nextToken": "optional" }.

• fs_mkdirp создает директории рекурсивно.

• fs_rmrf удаляет файлы или директории рекурсивно.

• fs_rename переименовывает или перемещает путь.

Инструменты конфигурации и автоматизации

ensure_package

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "state": "present",
  "sudoPassword": "optional"
}

state поддерживает present и absent.

ensure_service

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "state": "restarted",
  "sudoPassword": "optional"
}

state поддерживает started, stopped, restarted, enabled и disabled.

ensure_lines_in_file

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "lines": [
    "192.168.1.10 db-server",
    "192.168.1.20 cache-server"
  ],
  "state": "present",
  "createIfMissing": true,
  "sudoPassword": "optional"
}

state поддерживает present и absent.

patch_apply

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "diff": "@@ -1 +1 @@\n-old\n+new"
}

os_detect

Возвращает удаленную платформу, дистрибутив, версию, менеджер пакетов, систему инициализации, оболочку и временную директорию.

get_metrics

Возвращает