🔐 ssh-mcp-server

Name: ssh-mcp-server
Author: classfang

NPM Version GitHub forks GitHub Repo stars GitHub Issues or Pull Requests

SSH-сервер на базе MCP (Model Context Protocol), позволяющий удаленно выполнять SSH-команды через протокол MCP.

English Document | 中文文档

📝 Обзор проекта

ssh-mcp-server — это инструмент-мост, который позволяет ИИ-ассистентам и другим приложениям, поддерживающим протокол MCP, выполнять удаленные SSH-команды через стандартизированный интерфейс. Это позволяет ИИ-ассистентам безопасно управлять удаленными серверами, выполнять команды и получать результаты, не раскрывая учетные данные SSH напрямую ИИ-моделям.

Приглашаем присоединиться к группе в WeChat:

✨ Ключевые особенности

🔒 Безопасные соединения: Поддержка нескольких методов безопасного SSH-подключения, включая аутентификацию по паролю и по закрытому ключу (с поддержкой парольной фразы)
🛡️ Контроль безопасности команд: Точное управление диапазоном разрешенных команд с помощью гибких механизмов «черных» и «белых» списков для предотвращения опасных операций
🔄 Стандартизированный интерфейс: Соответствие спецификациям протокола MCP для бесшовной интеграции с ИИ-ассистентами, поддерживающими этот протокол
📂 Передача файлов: Поддержка двусторонней передачи файлов: загрузка локальных файлов на серверы или скачивание файлов с серверов
🔑 Изоляция учетных данных: Учетные данные SSH управляются полностью локально и никогда не передаются ИИ-моделям, что повышает безопасность
🚀 Готовность к работе: Можно запускать напрямую через NPX без глобальной установки, что делает развертывание удобным и быстрым

📦 Репозиторий с открытым исходным кодом

GitHub: https://github.com/classfang/ssh-mcp-server

NPM: https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server

🛠️ Список инструментов

Инструмент	Название	Описание
execute-command	Инструмент выполнения команд	Выполнение SSH-команд на удаленных серверах и получение результатов
upload	Инструмент загрузки файлов	Загрузка локальных файлов в указанные места на удаленных серверах
download	Инструмент скачивания файлов	Скачивание файлов с удаленных серверов в указанные локальные места
list-servers	Инструмент списка серверов	Список всех доступных конфигураций SSH-серверов

📚 Использование

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

⚠️ Важно: В конфигурационных файлах MCP каждый аргумент командной строки и его значение должны быть отдельными элементами в массиве args. НЕ объединяйте их пробелами. Например, используйте "--host", "192.168.1.1" вместо "--host 192.168.1.1".

⚙️ Параметры командной строки

Options:
  --config-file       JSON configuration file path (recommended for multiple servers)
  --ssh-config-file   SSH config file path (default: ~/.ssh/config)
  --ssh               SSH connection configuration (can be JSON string or legacy format)
  -h, --host          SSH server host address or alias from SSH config
  -p, --port          SSH server port
  -u, --username      SSH username
  -w, --password      SSH password
  -k, --privateKey    SSH private key file path
  -P, --passphrase    Private key passphrase (if any)
  -W, --whitelist     Command whitelist, comma-separated regular expressions
  -B, --blacklist     Command blacklist, comma-separated regular expressions
  -s, --socksProxy    SOCKS proxy server address (e.g., socks://user:password@host:port)
  --allowed-local-paths Additional allowed local paths for upload/download, comma-separated
  --pty               Allocate pseudo-tty for command execution (default: true)
  --pre-connect       Pre-connect to all configured SSH servers on startup

🔑 Использование пароля

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456"
      ]
    }
  }
}

🔐 Использование закрытого ключа

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa"
      ]
    }
  }
}

🔏 Использование закрытого ключа с парольной фразой

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa",
        "--passphrase", "pwd123456"
      ]
    }
  }
}

📋 Использование ~/.ssh/config

Вы можете использовать псевдонимы хостов, определенные в вашем файле ~/.ssh/config. Сервер автоматически считает параметры подключения из SSH-конфигурации:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "myserver"
      ]
    }
  }
}

Предположим, ваш ~/.ssh/config содержит:

Host myserver
    HostName 192.168.1.1
    Port 22
    User root
    IdentityFile ~/.ssh/id_rsa

Вы также можете указать путь к пользовательскому файлу конфигурации SSH:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "myserver",
        "--ssh-config-file", "/path/to/custom/ssh_config"
      ]
    }
  }
}

Примечание: Параметры командной строки имеют приоритет над значениями из конфигурации SSH. Например, если вы укажете --port 2222, это переопределит порт из конфигурации SSH.

🌐 Использование SOCKS-прокси

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--socksProxy", "socks://username:password@proxy-host:proxy-port"
      ]
    }
  }
}

📝 Использование «белого» и «черного» списков команд

Используйте параметры --whitelist и --blacklist для ограничения диапазона исполняемых команд. Несколько шаблонов разделяются запятыми. Каждый шаблон — это регулярное выражение, используемое для сопоставления команд.

Пример: Использование «белого» списка команд

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--whitelist", "^ls( .*)?,^cat .*,^df.*"
      ]
    }
  }
}

Пример: Использование «черного» списка команд

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--blacklist", "^rm .*,^shutdown.*,^reboot.*"
      ]
    }
  }
}

Примечание: Если указаны и «белый», и «черный» списки, система сначала проверит, находится ли команда в «белом» списке, а затем — в «черном». Команда должна пройти обе проверки, чтобы быть выполненной.

🧩 Пример мульти-SSH подключения

Существует три способа настройки нескольких SSH-подключений:

📄 Способ 1: Использование конфигурационного файла (рекомендуется)

Создайте JSON-файл конфигурации (например, ssh-config.json):

Формат массива:

[
  {
    "name": "dev",
    "host": "1.2.3.4",
    "port": 22,
    "username": "alice",
    "password": "{abc=P100s0}",
    "socksProxy": "socks://127.0.0.1:10808"
  },
  {
    "name": "prod",
    "host": "5.6.7.8",
    "port": 22,
    "username": "bob",
    "password": "yyy",
    "socksProxy": "socks://127.0.0.1:10808"
  }
]

Формат объекта:

{
  "dev": {
    "host": "1.2.3.4",
    "port": 22,
    "username": "alice",
    "password": "{abc=P100s0}",
    "socksProxy": "socks://127.0.0.1:10808"
  },
  "prod": {
    "host": "5.6.7.8",
    "port": 22,
    "username": "bob",
    "password": "yyy",
    "socksProxy": "socks://127.0.0.1:10808"
  }
}

Затем используйте параметр --config-file:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--config-file", "ssh-config.json"
      ]
    }
  }
}

🔧 Способ 2: Использование формата JSON с параметром --ssh

Вы можете передавать строки конфигурации в формате JSON напрямую:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--ssh", "{\"name\":\"dev\",\"host\":\"1.2.3.4\",\"port\":22,\"username\":\"alice\",\"password\":\"{abc=P100s0}\",\"socksProxy\":\"socks://127.0.0.1:10808\"}",
        "--ssh", "{\"name\":\"prod\",\"host\":\"5.6.7.8\",\"port\":22,\"username\":\"bob\",\"password\":\"yyy\",\"socksProxy\":\"socks://127.0.0.1:10808\"}"
      ]
    }
  }
}

📝 Способ 3: Устаревший формат через запятую (обратная совместимость)

Для простых случаев без специальных символов в паролях вы все еще можете использовать устаревший формат:

npx @fangjunjie/ssh-mcp-server \
  --ssh "name=dev,host=1.2.3.4,port=22,user=alice,password=xxx" \
  --ssh "name=prod,host=5.6.7.8,port=22,user=bob,password=yyy"

⚠️ Примечание: Устаревший формат может вызвать проблемы с паролями, содержащими специальные символы, такие как =, ,, {, }. Используйте Способ 1 или Способ 2 для паролей со специальными символами.

В вызовах инструментов MCP укажите имя подключения через параметр connectionName. Если он опущен, используется подключение по умолчанию.

Пример (выполнение команды для подключения 'prod'):

{
  "tool": "execute-command",
  "params": {
    "cmdString": "ls -al",
    "connectionName": "prod"
  }
}

Пример (выполнение команды с параметрами тайм-аута):

{
  "tool": "execute-command",
  "params": {
    "cmdString": "ping -c 10 127.0.0.1",
    "connectionName": "prod",
    "timeout": 5000
  }
}

⏱️ Тайм-аут выполнения команды

Инструмент execute-command поддерживает параметры тайм-аута, чтобы предотвратить бесконечное зависание команд:

timeout: Тайм-аут выполнения команды в миллисекундах (необязательно, по умолчанию 30000 мс)
Ответы об ошибках включают поля code, message и retriable для более удобной обработки на стороне агента

Это особенно полезно для таких команд, как ping, tail -f или других длительных процессов, которые могут блокировать выполнение.

🗂️ Список всех SSH-серверов

Вы можете использовать инструмент MCP list-servers для получения всех доступных конфигураций SSH-серверов:

Пример вызова:

{
  "tool": "list-servers",
  "params": {}
}

Пример ответа:

[
  { "name": "dev", "host": "1.2.3.4", "port": 22, "username": "alice" },
  { "name": "prod", "host": "5.6.7.8", "port": 22, "username": "bob" }
]

🛡️ Соображения безопасности

Этот сервер предоставляет мощные возможности для выполнения команд и передачи файлов на удаленных серверах. Чтобы обеспечить его безопасное использование, пожалуйста, учитывайте следующее:

«Белый список» команд: Настоятельно рекомендуется использовать опцию --whitelist для ограничения набора команд, которые могут быть выполнены. Без «белого списка» на удаленном сервере может быть выполнена любая команда, что может представлять серьезную угрозу безопасности.
Безопасность закрытого ключа: Сервер считывает закрытый ключ SSH в память. Убедитесь, что машина, на которой запущен ssh-mcp-server, защищена. Не открывайте доступ к серверу из ненадежных сетей.
Отказ в обслуживании (DoS): Сервер не имеет встроенного ограничения скорости запросов. Злоумышленник потенциально может провести DoS-атаку, перегрузив сервер запросами на подключение или передачей больших файлов. Рекомендуется запускать сервер за брандмауэром или обратным прокси-сервером с возможностями ограничения скорости.
Обход пути (Path Traversal): Сервер имеет встроенную защиту от атак обхода пути в локальной файловой системе. Тем не менее, важно помнить о путях, используемых в командах upload и download.
Область локальной передачи: По умолчанию локальная передача файлов ограничена текущей рабочей директорией. Используйте --allowed-local-paths или allowedLocalPaths в конфигурации только для явно доверенных директорий.

ssh-mcp-server