mcp-ssh-tool

👁 npm version
👁 CI
👁 Security
👁 Official MCP Registry
👁 License: MIT
👁 npm downloads

Промышленный MCP-инструмент для SSH-автоматизации, предназначенный для операторов, разработчиков и ИИ-клиентов. mcp-ssh-tool открывает постоянные SSH-сессии и предоставляет безопасные, структурированные инструменты для выполнения команд, операций с файлами, передачи данных, создания туннелей, управления пакетами/службами, получения метрик, ресурсов и использования готовых промптов.

Версия v2 безопасна по умолчанию: включена строгая проверка хост-ключей, отключен вход под root, выполнение sudo ограничено политиками, деструктивные команды и изменения файловой системы запрещены, если это не разрешено политикой, а удаленный HTTP-сервер запускается только на loopback-интерфейсе, если не настроены bearer-авторизация и разрешенные источники (origins).

Почему этот сервер

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

• Качество MCP: stdio для локальных клиентов, Streamable HTTP для удаленных клиентов, устаревший SSE доступен только через явный флаг совместимости.

• Инструменты для ИИ: стабильные схемы вывода, structuredContent, аннотации для операций (только чтение/деструктивные/идемпотентные), ресурсы и курируемые промпты.

• Операции: TTL сессий/вытеснение, тайм-ауты команд, проверка контрольных сумм при передаче, реальное SSH-проброс, метрики Prometheus и хуки OpenTelemetry.

• Портативность: приоритет SFTP, резервные механизмы оболочки POSIX/BusyBox для базовых операций с файлами и четкие границы поддержки.

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

Запуск без установки:

npx -y mcp-ssh-tool --version

Или установите глобально:

npm install -g mcp-ssh-tool

Добавьте stdio MCP-сервер в ваш клиент:

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

Используйте его из вашего MCP-клиента:

Open a safe SSH session to prod-1 as deploy, inspect host capabilities, then show disk usage.

Требования

• Node.js 22.22.2+ или 24.14.1+ (только LTS)

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

• Заполненный файл known_hosts для строгой проверки хостов или явная политика хост-ключей для каждой сессии

Транспорты

Запуск HTTP вне loopback-интерфейса запрещен, если не настроены --bearer-token-file и разрешенные источники.

Безопасные настройки по умолчанию

Параметр сессии policyMode: "explain" возвращает план/вердикт без выполнения. Используйте его перед внесением изменений, если ИИ-клиенту нужно оценить риски.

Пример политики

Установите SSH_MCP_POLICY_FILE=/etc/mcp-ssh-tool/policy.json:

{
 "mode": "enforce",
 "allowRootLogin": false,
 "allowRawSudo": false,
 "allowDestructiveCommands": false,
 "allowDestructiveFs": false,
 "allowedHosts": ["^prod-[0-9]+\\.example\\.com$"],
 "commandAllow": ["^(uname|df|uptime|systemctl status)\\b"],
 "commandDeny": ["rm\\s+-rf\\s+/", "shutdown", "reboot"],
 "pathAllowPrefixes": ["/tmp", "/var/tmp", "/home/deploy"],
 "pathDenyPrefixes": ["/etc/shadow", "/etc/sudoers", "/boot", "/dev", "/proc"]
}

Для простых развертываний можно использовать переменные окружения, такие как SSH_MCP_ALLOW_RAW_SUDO=true, SSH_MCP_ALLOWED_HOSTS=prod-1.example.com или SSH_MCP_PATH_ALLOW_PREFIXES=/tmp,/home/deploy.

Основные инструменты

• ssh_open_session, ssh_close_session, ssh_list_sessions, ssh_ping, ssh_list_configured_hosts, ssh_resolve_host

• proc_exec, proc_sudo, proc_exec_stream

• fs_read, fs_write, fs_list, fs_stat, fs_mkdirp, fs_rmrf, fs_rename

• file_upload, file_download

• ensure_package, ensure_service, ensure_lines_in_file, patch_apply

• os_detect, get_metrics

• tunnel_local_forward, tunnel_remote_forward, tunnel_list, tunnel_close

Все инструменты возвращают текст плюс стабильный structuredContent. Метаданные инструментов включают заголовки, схемы вывода и аннотации, раскрывающие поведение (только чтение, деструктивное, идемпотентное и наличие внешних побочных эффектов).

Ресурсы и промпты

Ресурсы:

• mcp-ssh-tool://sessions/active

• mcp-ssh-tool://metrics/json

• mcp-ssh-tool://metrics/prometheus

• mcp-ssh-tool://ssh-config/hosts

• mcp-ssh-tool://policy/effective

• mcp-ssh-tool://audit/recent

• mcp-ssh-tool://capabilities/support-matrix

Промпты:

• safe-connect

• inspect-host-capabilities

• plan-mutation

• managed-config-change

Матрица поддержки

Примеры для клиентов

ChatGPT или Claude Desktop:

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

VS Code или Cursor:

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

MCP Inspector через HTTP:

printf '%s' 'super-secret-token' > .mcp-token
mcp-ssh-tool --transport=http --host 127.0.0.1 --port 3000 --bearer-token-file .mcp-token

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

Важные переменные окружения:

Устаревшие псевдонимы STRICT_HOST_KEY_CHECKING и SSH_MCP_STRICT_HOST_KEY все еще принимаются в течение одного цикла совместимости v2. Рекомендуется использовать SSH_MCP_HOST_KEY_POLICY.

Разработка

Используйте точную локальную среду выполнения из .nvmrc / .node-version, затем выполните:

npm ci
npm run check

Живые SSH-тесты являются опциональными:

RUN_SSH_INTEGRATION=1 npm run test:integration
RUN_SSH_E2E=1 npm run test:e2e

Локальные проверки качества:

• pre-commit: форматирует индексированные файлы и проверяет только индексированный TypeScript

• pre-push: запускает npm run check:push

• task hooks: запускает отслеживаемые npm-хуки плюс хуки .pre-commit-config.yaml, если установлен pre-commit

• ручная/полная проверка: task ci или npm run check

Владение CI/CD

Личный репозиторий https://github.com/oaslananka/mcp-ssh-tool является каноническим исходным репозиторием. Автоматический CI/CD, проверки безопасности цепочки поставок, доверенная публикация npm и публикация в MCP Registry выполняются только из https://github.com/oaslananka-lab/mcp-ssh-tool. Организационный репозиторий получает данные из канонического источника; рабочие процессы push и публикации в личном репозитории отключены.

Поле repository.url в npm-пакете намеренно указывает на организационный репозиторий, чтобы проверка происхождения npm могла подтвердить, что опубликованный артефакт был создан тем же репозиторием GitHub Actions, который его собрал.

См. docs/ci-cd-topology.md для получения информации о синхронизации организации, процессе выпуска и руководстве по ручному восстановлению.

Документация

• ARCHITECTURE.md

• SECURITY_DECISIONS.md

• MIGRATION.md

• docs/ci-cd-topology.md

• docs/development.md

• docs/release.md

• docs/doppler.md

• docs/operations.md

• docs/branch-protection.md

• docs/maintenance-policy.md

• docs/api-stability.md

• docs/threat-model.md

• docs/configuration.md

• docs/security-model.md

• docs/troubleshooting.md

• docs/enterprise-deployment.md

Лицензия

MIT License. См. LICENSE.

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• connector_statusA
• ensure_lines_in_fileA
• ensure_packageC
• ensure_serviceB
• file_downloadA
• file_uploadB
• fs_listC
• fs_mkdirpA