MCP SSH Manager - SSH Remote Server Management via Model Context Protocol 🚀

A Model Context Protocol (MCP) server that enables Claude Code and OpenAI Codex to manage multiple SSH connections. Execute commands, transfer files, manage databases, create backups, monitor health, and automate DevOps tasks across your servers — directly from your AI assistant.

<div align="center">

</div> <p align="center"> <img src="docs/images/ssh-manager-cli-menu.png" alt="ssh-manager interactive CLI menu" width="900"> </p>

---

🎉 What's New in v3.7.0

🔗 Per-server SSH agent forwarding (ForwardAgent) (Released: July 13, 2026)

• New opt-in FORWARD_AGENT / forward_agent option (#53 — requested by @raphaelbahat in #52) — enable the equivalent of OpenSSH's ForwardAgent yes per server, so processes on the remote host can authenticate to other SSH hosts using the keys in your local ssh-agent (e.g. git clone over SSH on a remote server using your local GitHub key), without copying any private key to the server.
• Safe by construction — requires a running local agent (SSH_AUTH_SOCK); the flag is ignored when no agent is present, so it never breaks a connection. Boolean parsing treats only true/1/yes/on as enabled — FORWARD_AGENT=false stays off.
• ⚠️ Defaults to false — agent forwarding lets anyone with root on the remote host use your loaded keys for the life of the connection, so enable it only for servers you trust. See the new SSH Agent Forwarding section in the docs.

SSH_SERVER_MYSERVER_FORWARD_AGENT=true

Read full changelog →

---

Previous Releases

v3.6.7 - Security: command injection fix in the database helpers (July 11, 2026)

• 🔒 Every ssh_db_* argument is now shell-quoted (#51 — responsibly disclosed by Ugur Ozer, Aeon AI Risk Management (http://airiskmanagement.ca), see #48) — caller-controlled values (ssh_db_list most notably, which stayed allowed in readonly/restricted modes) were interpolated into shell-evaluated strings, allowing arbitrary command execution on the SSH target. A centralized shellQuote() now wraps every value across all 15 builders, guarded by a 648-combination injection test. Full changelog →

v3.6.6 - SUDO_PASSWORD / DEFAULT_DIR / ssh_sync key auth work again (July 11, 2026)

• 🔑 camelCase config field reads (#50 — thanks @egoan82) — since the v3.0.0 ConfigLoader refactor, ssh_execute_sudo ignored SUDO_PASSWORD, DEFAULT_DIR was ignored by ssh_execute/ssh_group_execute/ssh_list_servers, and ssh_sync never passed the configured SSH key to rsync. All aligned with the loader's camelCase fields, with a regression test locking the loader output shape. Full changelog →

v3.6.5 - ssh_db_query shell-injection security fix + real row_count (June 30, 2026)

• 🔒 Queries are delivered on stdin via a single-quoted heredoc (#44, #45 — thanks @technophile77) — the remote shell no longer parses backticks/$(…) inside queries (which corrupted backtick identifiers and let the "SELECT-only" tool run arbitrary shell commands), and row_count now reflects each engine's real output instead of counting wrapper lines. Full changelog →

v3.6.4 - Internal cleanup + a dead-code quality gate (June 18, 2026)

• 🧹 Dead-code removal (−343 lines), zero behavioral change — removed 27 unused exports and 2 duplicate exports; the MCP server and CLI behave identically (command builders/parsers byte-identical, all 37 tools verified end-to-end). A calibrated knip.json plus a blocking knip CI step keep unused code from creeping back. Full changelog →

v3.6.3 - ssh_sync reports the real transfer count (June 18, 2026)

• 📊 No more false "No files needed to be transferred" (#42 — thanks @MakksSh) — fixed rsync --stats parsing: --stats is always passed now, and rsync 2.x/3.x wording, openrsync's B suffix, and locale separators are all handled. Full changelog →

v3.6.2 - Richer tool descriptions (June 9, 2026)

• 📝 All 37 tool descriptions rewritten — every MCP tool now documents its real behavior (side effects, destructive vs read-only nature, idempotency, sudo/auth requirements, security-mode gating, parameter semantics) instead of a 4-to-10-word summary. Agents now know the consequences before invoking a tool; no behavioral change — only description strings changed. Full changelog →

v3.6.1 - Teardown hygiene follow-up (June 9, 2026)

• 🔌 Module-level timers no longer pin the event loop (follow-up to #41) — tunnel-manager.js and session-manager.js registered module-level setIntervals that were never unref()'d, so importing either module kept Node's event loop alive. Both are now unref()'d. Full changelog →

v3.6.0 - Live config hot reload + stdio lifecycle fix (June 9, 2026)

• ♻️ Configuration hot reload (#40 — thanks @EnjoySR) — add or edit a server in your .env/TOML and the running MCP server picks it up on the next call, no restart. A ServerConfigManager reloads lazily on file-signature change (path + mtime + size); a failed reload keeps the last known-good config; real process.env vars keep top priority. No watcher, no polling.
• 🔌 No more orphaned stdio processes (#41 — thanks @LegendaryGatz) — a stdio MCP server is torn down by stdin EOF / SIGTERM, not SIGINT; with only a SIGINT handler every session leaked a ~83 MB node process. Shutdown is now idempotent across SIGINT/SIGTERM/SIGHUP/stdin-close, timers are unref()'d, and the process exits ~10 ms after teardown instead of never. Full changelog →

v3.5.1 - Robust SSH ping health-check on Windows/OpenSSH (May 26, 2026)

• 🪟 Healthy Windows sessions no longer reported as Dead (#39 — thanks @username77) — the liveness probe ran echo "ping" and cmd.exe echoed the quotes literally, failing a strict === 'ping' check and needlessly rebuilding live connections. Now uses echo ping parsed by a null-safe isPingAlive(stdout) helper (CRLF/quote/case-normalized), covered by tests/test-ssh-ping.js. Full changelog →

v3.5.0 - Per-server security modes — readonly / restricted + audit log (May 18, 2026)

A second authorization layer that filters tool invocations inside the MCP server, complementing the existing client-side autoApprove. Useful when sharing the MCP with a third-party agent, a CI bot, or any client where ssh_execute shouldn't be unconditionally trusted.

• 🔒 Three modes, opt-in per server (no MODE field = identical to v3.4.x):
  • unrestricted (default) — strict no-op. evaluatePolicy() early-returns on the first line, zero overhead.
  • readonly — blocks mutating tools (ssh_upload, ssh_deploy, ssh_sync, ssh_execute_sudo, ssh_backup_*, ssh_db_import/dump, plus action-gated ssh_key_manage accept|remove, ssh_alert_setup set, ssh_process_manager kill) AND applies a built-in denylist on ssh_execute (rm, mv, dd, mkfs, chmod, chown, sudo, systemctl restart/stop, docker rm/stop, pipe-to-sh, redirect outside /tmp, curl|sh, etc.).
  • restricted — every command must match at least one ALLOW_PATTERNS regex AND no DENY_PATTERNS regex. DENY wins. With no ALLOW_PATTERNS everything is refused (fail-closed).
• 📝 Audit log — opt-in JSONL per server (SSH_SERVER_<N>_AUDIT_LOG=/path/to/audit.jsonl). Records ts, server, tool, args, allowed, reason on denial, exitCode/success on execution. Sensitive arg fields (password, passphrase, sudoPassword, token, secret, apikey) are replaced with ***.
• 🪄 Command aliases expanded BEFORE policy evaluation — a DENY pattern can't be bypassed via an alias.
• ♻️ Backward-compatible by design — a v3.4.x .env or TOML loads identically. No MODE field → zero behavior change. The interactive wizard (ssh-manager server add) defaults all three new prompts to skip. All 13 pre-existing tests pass unmodified. New tests/test-policy.js adds 26 tests covering modes, DENY > ALLOW precedence, invalid-regex handling, redaction, and the backward-compat fast path. Full reference →

v3.4.1 - Modern OpenSSH 9.x compatibility (May 16, 2026)

• 🔐 Expanded SSH algorithm list — handshake against OpenSSH 9.x out of the box (#32)
  • KEX: curve25519-sha256 (+@libssh.org), diffie-hellman-group15-sha512, diffie-hellman-group16-sha512
  • Server host key: rsa-sha2-512, rsa-sha2-256 (RFC 8332)
  • Cipher: aes128-gcm@openssh.com, aes256-gcm@openssh.com
  • HMAC: hmac-sha2-256-etm@openssh.com, hmac-sha2-512-etm@openssh.com, hmac-sha1-etm@openssh.com
  • Backward-compatible — legacy algorithms preserved at lower preference, older servers (CentOS 7, Debian 10) keep working. Thanks @YoungHong1992.

v3.4.0 - Windows OpenSSH support + shell-agnostic session sync (May 7, 2026)

• 🪟 Windows OpenSSH encoding & syntax fixes — UTF-16LE base64 PowerShell payloads (Ansible-style) + Set-Location replacing cd && (#31, thanks @WenKingSu)
• 🎯 Marker-based SSH session sync — UUID v4 protocol boundaries with ECHO: 0 PTY, real $? exit codes, no more "Timeout waiting for shell prompt" on custom/slow/AIX shells (#30, thanks @MakksSh)

v3.3.0 - ProxyCommand & Critical Fixes (May 2, 2026)

• 🔌 ProxyCommand support for SOCKS5 / custom proxy commands ([#24](https://github.com/bvisible/