Skip to main content
Glama
ssh-mcp

ssh-mcp

by votsie

ssh-mcp

Управление серверами по SSH для любого агента с поддержкой MCP, включая Codex, Cursor, Windsurf, Zed. MCP-сервер плюс три руководства, которые учат агента им пользоваться.

Умеет интерактивную консоль с эмуляцией терминала (nano, htop, whiptail, вендорские панели видны как читаемый экран, а не как каша из ESC-последовательностей), обмен файлами, туннели (локальный, удалённый, SOCKS5) и память о серверах, переживающую перезапуск.

Ключевая идея: работа без конфига

Ничего настраивать заранее не нужно. Пользователь диктует адрес, логин и пароль. Агент подключается, и только после успешного коннекта спрашивает, как назвать сервер, и сохраняет доступы. Дальше сервер адресуется по имени.

— подключись к 203.0.113.23, root, пароль XXX
   → подключился, Debian 12, ядро 6.1, отпечаток SHA256:...
   → как назвать этот сервер? [nl4] [vps-nl4] [srv-166]
— nl4
   → сохранено. Дальше просто «nl4».

Related MCP server: SSH MCP Server

Установка

Ставится в любой MCP-клиент одной строкой прямо из репозитория, включая Codex, Cursor, Windsurf, Zed и что угодно ещё, что умеет stdio-транспорт:

uvx --from git+https://github.com/votsie/ssh-mcp ssh-mcp

Готовые блоки конфигурации под каждый клиент, установка без uv, переменные окружения и обновление описаны в INSTALL.md.

Нужен только uv: он сам поставит нужный Python и библиотеки в изолированное окружение, в систему ничего не попадает.

Руководства достаются любому агенту

Клиенты поддерживают разные способы получения руководств, поэтому материал раздаётся тремя способами, и исходный материал хранится в src/ssh_mcp/guides/:

Способ

Кому

skills/*/SKILL.md

совместимые MCP-клиенты (собираются из источника, scripts/sync_skills.py)

инструкции при подключении

всем клиентам, которые их показывают модели

инструмент ssh_guide(topic)

всем без исключения: инструменты видит любой агент

Подсказки MCP (ssh-servers, ssh-interactive, ssh-ops) объявлены тоже, но опираться на них нельзя: многие клиенты их модели не показывают вовсе.

Состояние

Всё живёт в ~/.ssh-mcp/, вне любого git-репозитория:

servers.env      профили с паролями, права 0600 + icacls
known_hosts      закреплённые ключи хостов
memory/<имя>/    facts.json (проба) и notes.md (заметки)
history.jsonl    журнал всех действий
logs/            технический лог

~/.ssh/known_hosts читается, но никогда не переписывается: paramiko.HostKeys.save() нормализует файл целиком и выбросил бы комментарии и маркеры @cert-authority, на которые опирается настоящий ssh-клиент.

Модель угроз: скажем прямо

Пароли лежат открытым текстом, это осознанное требование, конфиг должен правиться блокнотом. Файл защищён правами владельца (на Windows именно через icacls /inheritance:r, потому что chmod на NTFS не запрещает ничего), но любой процесс, запущенный от вашего пользователя, прочитает его. Модель угроз та же, что у ~/.aws/credentials.

Блок-листа опасных команд нет и переспроса тоже нет. Так заказано. Агент выполнит rm -rf /, если его об этом попросить. Остаётся два смягчающих средства: журнал history.jsonl (это криминалистика, а не предотвращение) и рецепт «мёртвой руки» в скилле ssh-servers для правок, способных отрезать собственный доступ.

Секреты вычищаются из всех ответов и логов по набору известных строк. Это необходимо, а не косметика: Channel.get_pty() в paramiko шлёт пустое поле terminal modes и выключить эхо не позволяет, так что эхо целиком на совести sshd.

Настройки

Переменная

По умолчанию

Смысл

SSHM_HOME

~/.ssh-mcp

Каталог состояния

SSHM_CONNECT_TIMEOUT

20

Таймаут коннекта, банера и аутентификации

SSHM_CMD_TIMEOUT

300

Таймаут команды по умолчанию

SSHM_SHELL_TTL

1800

Простой, после которого сессия закрывается

SSHM_KEEPALIVE

30

Период keepalive

SSHM_DEBUG

—

Подробный лог

Разработка

.venv/Scripts/python.exe -m pytest -q

Тесты не ходят в сеть: в tests/sshd.py поднимается настоящий SSH-сервер на paramiko с парольной и ключевой аутентификацией, exec, эхо-оболочкой с альтернативным экраном и реальным пробросом direct-tcpip. Это покрывает коннект, drain-цикл, дедлайны, PTY, SOCKS5 и туннели.

Что не работает и не будет

  • Сессии и туннели не переживают перезапуск MCP-сервера. Оболочка на той стороне умирает вместе со своим окружением; воскрешать её означало бы врать.

  • Терминал эмулирует VT100/VT220 на чистом Python. 256 цветов, мышь и bracketed paste игнорируются, экран местами отличается от настоящего. При странностях помогает term="linux".

Прыжковые хосты

Если сервер закрыт фаерволом снаружи и виден только из своей же сети, укажите в профиле jump имя другого сохранённого сервера:

SSHM_RU2_JUMP='ru1'

Дальше ssh_run("ru2", ...) работает как обычно: соединение идёт каналом direct-tcpip, открытым с промежуточного сервера. Проверка ключа хоста при этом не ослабевает: сверяется ключ конечного сервера, а не промежуточного. Кольца в цепочке отлавливаются до попытки подключения.

Ключи PuTTY

.ppk версий 2 и 3 читаются напрямую (ssh_mcp.ppk), включая шифрование Argon2id. puttygen не нужен, а на Windows его обычно и нет. MAC проверяется всегда: он отличает неверную парольную фразу от повреждённого файла, а это разные беды с разным лечением.

Available Tools

29 tools
ssh_connectA

Подключиться к серверу по имени либо по адресу с логином и паролем/ключом.

Если сервер неизвестен, подключение происходит без всякого конфига, а доступы НЕ сохраняются: в ответе придёт next_action с требованием спросить у пользователя имя и вызвать ssh_save_server. Не придумывайте имя сами.

Inputs: target (required), port, user, probe, +4 more.

ssh_copy_betweenA

Перекинуть файл с одного сервера на другой через эту машину.

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

Inputs: dst_path (required), src_path (required), dst_server (required), src_server (required).

ssh_disconnectB

Закрыть соединение с сервером вместе с его сессиями и туннелями.

Inputs: target.

ssh_downloadB

Скачать файл с сервера на эту машину и сверить контрольную сумму.

Inputs: server (required), local_path (required), remote_path (required), max_bytes.

ssh_facts_refreshB

Перечитать факты о сервере: ОС, ядро, диск, установленное ПО, порты.

Inputs: server (required).

ssh_file_readB

Прочитать текстовый файл с сервера. Большие файлы обрезаются.

Inputs: server (required), remote_path (required), max_bytes.

ssh_file_writeB

Положить файл на сервер атомарно и идемпотентно.

Порядок намеренный: сверить хеш, залить во временный, проверить временный, переставить через rename. На месте боевого файла никогда не оказывается непроверенное содержимое, а повторный вызов с тем же текстом ничего не делает и честно сообщает changed=false.

Inputs: server (required), content (required), remote_path (required), mode, +3 more.

ssh_forget_host_keyA

Снять закрепление ключа хоста.

Вызывать только после того, как пользователь явно подтвердил, что сервер был пересоздан. Молча повторять подключение после расхождения ключей — ровно то, чего добивается перехватчик.

Inputs: host (required), port.

ssh_forget_serverA

Удалить сохранённый сервер. Заметки удаляются только по явному запросу.

Inputs: name (required), delete_memory.

ssh_guideA

Подробное руководство по работе с этими инструментами.

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

Inputs: topic.

ssh_historyB

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

Inputs: limit, server.

ssh_import_legacyA

Импортировать серверы из старого блочного servers.env.

По умолчанию только показывает, что будет импортировано: покажите результат пользователю прежде, чем писать.

Inputs: path (required), dry_run.

ssh_keys_listB

Показать имена клавиш, которые понимает ssh_shell_send.

Inputs: no named parameters.

ssh_list_dirC

Показать содержимое каталога на сервере.

Inputs: server (required), limit, remote_path.

ssh_notes_addB

Записать заметку о сервере — она переживёт перезапуск и новую сессию.

Inputs: note (required), server (required), tags.

ssh_notes_getC

Прочитать факты и заметки о сервере.

Inputs: server (required), limit, query.

ssh_runA

Выполнить команду на сервере и дождаться результата.

Для всего, что длится дольше пары минут (apt upgrade, docker pull), берите background=true: команда отвяжется от сессии и переживёт её, а вывод уйдёт в файл. Увеличивать таймаут вместо этого — путь к зависшему вызову.

Inputs: server (required), command (required), check, stdin, +3 more.

ssh_run_manyA

Выполнить одну команду на нескольких серверах параллельно.

Сбой одного сервера не отменяет остальные — в ответе будет и результат, и ошибка, каждая рядом со своим именем.

Inputs: command (required), servers (required), timeout, max_workers.

ssh_save_serverA

Сохранить сервер под именем, которое назвал пользователь.

Обычно вызывается сразу после ssh_connect с его pending_id — тогда живое соединение просто переименовывается и переподключения не происходит.

Inputs: name (required), host, port, tags, +8 more.

ssh_shell_closeC

Закрыть интерактивную сессию.

Inputs: session (required).

ssh_shell_openA

Открыть интерактивную оболочку на сервере.

Нужна там, где команда что-то спрашивает или рисует полноэкранный интерфейс: nano, whiptail, htop, меню панелей. Для обычных команд берите ssh_run — он дешевле. Сессию по окончании закрывайте.

Inputs: server (required), cols, rows, term, +2 more.

ssh_shell_readB

Дочитать вывод сессии, ничего не отправляя — для длящихся команд.

Inputs: session (required), view, expect, idle_ms, +1 more.

ssh_shell_resizeB

Изменить размер окна сессии. Полезно, если TUI обрезает содержимое.

Inputs: cols (required), rows (required), session (required).

ssh_shell_sendA

Отправить текст и/или нажатия клавиш в сессию и дождаться реакции.

Работайте циклом: отправили — прочитали — посмотрели на экран — решили. Две отправки подряд вслепую почти всегда приводят к застрявшей сессии.

Inputs: session (required), keys, text, view, +4 more.

ssh_shell_send_secretA

Ввести пароль в приглашение sudo, passwd или установщика.

Предпочитайте server_password: тогда пароль берётся из хранилища внутри процесса и вообще не проходит через переписку. Никогда не отправляйте пароль обычным ssh_shell_send — тот пишет текст в журнал.

Inputs: session (required), value, idle_ms, timeout_s, +1 more.

ssh_statusA

Показать сохранённые серверы, живые соединения, сессии и туннели.

Первый инструмент, с которого стоит начинать: отвечает на вопрос «что у меня уже есть» одним вызовом.

Inputs: verbose.

ssh_tunnel_closeA

Закрыть туннель. Без аргумента закрывает все.

Inputs: tunnel_id.

ssh_tunnel_openB

Поднять туннель до сервера.

Панель, слушающую на 127.0.0.1:2053, открывают как kind='local' с dest_host='127.0.0.1', dest_port=2053 — и она становится доступна по возвращённому адресу. Туннель живёт до конца сессии Claude Code.

Inputs: server (required), bind, kind, dest_host, +2 more.

ssh_uploadA

Залить локальный файл на сервер и проверить, что он долетел целым.

Для содержимого, которое вы сами составили, лучше ssh_file_write — он идемпотентен, умеет проверку конфига и делает резервную копию.

Inputs: server (required), local_path (required), remote_path (required), mode, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 29 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (run vs shell, upload vs file_write, notes vs facts), but ssh_run and ssh_shell_open could be confused for interactive vs non-interactive execution, and ssh_upload vs ssh_file_write overlap in file transfer. The descriptions help disambiguate, but the boundaries require careful reading.

    Naming Consistency4/5

    The naming follows a consistent ssh_<verb>_<noun> pattern (ssh_run, ssh_upload, ssh_shell_open, ssh_tunnel_open). Minor deviations like ssh_status, ssh_guide, and ssh_import_legacy break the verb_noun pattern slightly, but the overall convention is predictable.

    Tool Count3/5

    29 tools is on the heavy side for an SSH server, but the breadth is justified by covering connections, file operations, interactive shells, tunnels, notes, and history. It feels comprehensive rather than bloated, though some tools (ssh_keys_list, ssh_shell_resize) are niche.

    Completeness5/5

    The tool surface covers the full SSH lifecycle: connection management (connect, disconnect, save, forget), file operations (upload, download, read, write, list, copy), interactive sessions (open, send, read, resize, close), tunnels (open, close), and auxiliary data (notes, facts, history, keys). No obvious dead ends for common workflows.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to maintain persistent SSH terminal sessions and transfer files to/from remote servers. Allows stateful command execution, natural language server management, and seamless file operations through SSH connections.
      10 npm
      35
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to securely execute commands, transfer files, and manage port forwarding on remote servers via SSH.
      164 npm
      38
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to have persistent, fully interactive SSH sessions into remote hosts, behaving like a local terminal.
      14 npm
      2
      MIT