ssh-mcp — безопасный SSH-доступ для ИИ-агентов через MCP

ssh-mcp — это MCP-сервер на Go, который даёт ИИ-ассистентам безопасный и ограниченный доступ к удалённым серверам по SSH. В отличие от сырого shell (небезопасно, без ограничений) или полного отсутствия SSH-доступа, ssh-mcp работает посередине: агент получает небольшой набор аудируемых инструментов, каждый из которых проходит через опциональную whitelist/blacklist-политику команд и ограничения путей.

Сервер работает по stdio и совместим с любым MCP-клиентом: Claude Desktop, Claude Code, Cursor, Devin, VS Code и Cline. Он предоставляет восемь инструментов — выполнение команд, SFTP-перенос файлов, синхронизацию директорий, проброс портов и сбор статуса удалённой системы.

Чем отличается

У типового ассистента, которому нужен доступ к серверу, обычно два варианта: получить сырой shell или не получить ничего. ssh-mcp закрывает эту дыру политиками:

• Command policy — regex-паттерны whitelist и blacklist проверяют каждую команду перед выполнением. Без whitelist разрешены все команды, а при старте пишется предупреждение в лог.
• Ограничение путей — allowed_local_paths и allowed_remote_paths придержива SFTP-операции к заданным каталогам и отклоняют path traversal.
• Секреты через переменные окружения — пароль, passphrase и код 2FA передаются через env-переменные, никогда в командной строке.
• Hot-reload — при запуске с --config файл конфигурации отслеживается и перезагружается без перезапуска сервера. Добавление, удаление или изменение серверов вступает в силу в течение секунд.

Инструменты

Подробные аргументы и примеры — в Tools.

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

1. AI-клиент отправляет MCP-запрос tools/call через stdin процесса ssh-mcp.
2. Сервер определяет целевое подключение (по умолчанию — первый настроенный сервер).
3. Команда или передача файлов валидируется по командной политике сервера и разрешённым путям.
4. Операция выполняется по SSH/SFTP (или открывается проброс порта) с заданным таймаутом и лимитом вывода.
5. Структурированный результат возвращается клиенту. Ошибки несут стабильный код ssh.ToolError и флаг Retriable — агент сам решает, повторять ли попытку.

Архитектура, раскладка пакетов и полный поток данных запроса описаны в Architecture.

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

git clone https://github.com/overklassniy/ssh-mcp.git
cd ssh-mcp
make build

Минимальный ssh-mcp.toml:

[[server]]
name = "web"
host = "example.com"
username = "deploy"
port = 22
private_key = "~/.ssh/id_ed25519"

Регистрация в клиенте:

ssh-mcp install --client claude-code --config ./ssh-mcp.toml

Перезапустите AI-клиента и попросите агента:

Use the list-servers tool.

Вы увидите свой сервер со статусом connected или disconnected.

Установка

Три способа установки дают один и тот же результат — запись MCP-сервера в конфиг клиент. Полное руководство — в Installation.

• Локальный бинарник — make build, затем ssh-mcp install --client <client> --config ./ssh-mcp.toml. Поддерживаемые клиенты: claude-desktop, claude-code, cursor, Devin, vscode, cline.

• Docker — ssh-mcp install --client <client> --docker --config ./ssh-mcp.toml. По умолчанию используется ghcr.io/overklassniy/ssh-mcp:latest.

• MCPB-бандл — скачайте .mcpb со страницы Releases и откройте в клиенте, который поддерживает MCPB (Claude Desktop, Claude Code, MCP for Windows).

• Вставка конфига вручную — подкоманда snippet генерирует готовую запись сервера для вашего набора параметров:

  ssh-mcp snippet --docker --host 192.168.1.1 --user root
  ssh-mcp snippet --gorun  --host 192.168.1.1 --user root

  Docker использует опубликованный multi-arch образ; --gorun запускает go run github.com/overklassniy/ssh-mcp/cmd/ssh-mcp@latest (Go-аналог npx -y <package>, требует Go-тулчейн). Секреты остаются в блоке env, никогда в args.

Односерверный режим позволяет обойтись без TOML-файла, передав параметры подключения флагами:

ssh-mcp --host example.com --user deploy --port 22 \
  --private-key ~/.ssh/id_ed25519

Вставка конфига через go run

Если установлен Go-тулчейн (Go 1.26+), бинарник собирать не нужно. Добавьте запись в mcpServers конфига клиента (например, ~/.codeium/Devin/mcp_config.json):

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "go",
      "args": [
        "run",
        "github.com/overklassniy/ssh-mcp/cmd/ssh-mcp@latest",
        "--host", "192.168.1.1",
        "--port", "22",
        "--user", "root",
        "--transport", "exec"
      ],
      "env": {
        "SSH_MCP_PASSWORD": "your-password"
      }
    }
  }
}

При первом запуске go run скачивает и компилирует последний тегированный релиз и запускает stdio MCP-сервер; дальше работает кэш сборки. Для авторизации по приватному ключу замените SSH_MCP_PASSWORD на SSH_MCP_PASSPHRASE и добавьте --private-key в args. Закрепить версию можно, заменив @latest на @v1.0.0.

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

ssh-mcp настраивается TOML-файлом: секция [defaults] верхнего уровня и одна или несколько записей [[server]]. Каждый сервер наследует от [defaults], затем от встроенных значений по умолчанию, и валидируется при старте.

[defaults]
command_timeout     = "30s"
connection_timeout  = "30s"
sftp_timeout        = "5m"
keepalive_interval  = "10s"
keepalive_count_max = 3
max_output_bytes    = 10485760
transport           = "exec"

[[server]]
name     = "web"
host     = "web.example.com"
username = "deploy"
port     = 22
private_key = "~/.ssh/id_ed25519"
whitelist = ["^systemctl status .*", "^journalctl .*", "^ls .*"]
allowed_remote_paths = ["/var/log", "/srv"]
allowed_local_paths = ["~/downloads"]

Полная справка — методы аутентификации, командная политика, ограничения путей, keepalive, режимы транспорта и правила валидации — в Configuration.

Модель безопасности

ssh-mcp не проверяет ключи хостов удалённых серверов (InsecureIgnoreHostKey). Безопасность обеспечивается двумя механизмами, которые настраивает оператор:

• Command policy — regex-паттерны whitelist/blacklist проверяют каждую команду, включая отдельные probe-команды, используемые server-status, поэтому ограничительный whitelist нельзя обойти.
• Ограничение путей — allowed_local_paths и allowed_remote_paths придерживают SFTP-операции; удалённые пути должны быть абсолютными POSIX-путями.

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

Совместимость

• Клиенты — Claude Desktop, Claude Code, Cursor, Devin, VS Code, Cline.
• Платформы — Windows, macOS, Linux (amd64, arm64).
• Рантайм — Go 1.26+ для сборки или предсобранный бинарник из Releases.

Лицензия

MIT. Полный текст — в LICENSE. Тот же MIT указан в mcpb/manifest.json.

Проект вдохновлён classfang/ssh-mcp-server.