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.

---

🎉 What's New in v3.6.5

Security fix: ssh_db_query shell injection + a row-count fix (Released: June 30, 2026)

• 🔒 ssh_db_query no longer lets the remote shell parse your query (#44 — thanks @technophile77) — the builders interpolated the query into a double-quoted shell string (mysql -e "${query}", psql -c "${query}", mongo --eval "${query}"), so the remote shell evaluated backticks and $(…) before the database saw it. That both corrupted backtick identifiers (hyphenated DB names, cross-DB joins → empty results, no error) and let the "SELECT-only" tool run arbitrary shell commands on the host. The query is now delivered on stdin via a single-quoted heredoc, so only the database engine ever interprets it.
• 🔢 ssh_db_query reports the real row_count (#45 — thanks @technophile77) — it used to count the cosmetic JSON-wrapper line (1 row → 2, 0 rows → 2); it now derives the count from each engine's actual output (MySQL JSON entries, psql's (N rows) footer, MongoDB documents).

Read full changelog →

---

Previous Releases

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)
• ⏱️ ssh_execute timeout silently capped at 30 s — fixed (#28, #29)
• 🪟 Windows global install /bin/bash shim error — fixed (#22, #23)
• 🔧 server add blocked by missing rsync — rsync now optional (#26)
• 🔡 Hyphenated server names silently dropped — validation hardened (#25, #27)

v3.2.2 - Global Install Fix & CLI Binary (April 7, 2026)

• 🔧 Global install fixed: .env path resolution now uses a fallback chain instead of hardcoded __dirname — works correctly with npm install -g (#16, #19)
• Fallback chain: ~/.ssh-manager/.env → cwd/.env → ~/.env → project .env
• Auto-creates ~/.ssh-manager/.env on first ssh-manager server add
• 📦 ssh-manager CLI registered as binary: npm install -g now creates both mcp-ssh-manager and ssh-manager commands (#18)
• ⚡ Race condition fix: Server config is now fully loaded before the MCP server accepts requests

v3.2.0 - ProxyJump / Bastion Host Support (March 18, 2026)

• 🔀 ProxyJump support: Connect to servers behind bastion/jump hosts with a simple PROXYJUMP config field (#15)
• Chain multiple jumps (A → B → C) via recursive connections
• Circular dependency detection prevents infinite loops
• All tools work transparently through jump hosts
• 📦 npx support fixed: npx mcp-ssh-manager now works correctly (#14)

v3.1.5 - SSH Agent & Passphrase Support (March 5, 2026)

• 🔑 SSH Agent support: Automatically uses ssh-agent when SSH_AUTH_SOCK is available — passphrase-protected keys work transparently
• 🔐 Passphrase configuration: New passphrase field for both .env and TOML formats

Thanks to @snjax for the original contribution (#12).

v3.1.4 - Windows SSH Host Support (February 22, 2026)

• 🪟 Windows SSH host fix: Commands no longer fail on Windows hosts running OpenSSH (#10)
• New per-server platform config field (SSH_SERVER_FOO_PLATFORM=windows or platform = "windows" in TOML)
• When platform=windows, the Linux timeout/sh -c command wrapper is skipped and the SSH library's native timeout is used instead
• All tools (ssh_execute, ssh_tail, ssh_monitor, ssh_deploy, ssh_execute_sudo, ssh_group_execute) are platform-aware

v3.1.2 - Windows Compatibility Fix (February 9, 2026)

• 🪟 Windows support: Fixed crash on Windows where process.env.HOME is undefined (#8)
• Now uses os.homedir() for cross-platform compatibility (Linux, macOS, Windows)

v3.1.0 - Tool Activation System (November 15, 2025)

🎯 Context Usage Optimization

• 92% context reduction: Enable only the tools you need (minimal mode: 5 tools vs all 37)
• Tool management CLI: ssh-manager tools list/configure/enable/disable
• 6 tool groups: Core, Sessions, Monitoring, Backup, Database, Advanced
• Auto-approval export: Generate Claude Code auto-approval configs

v3.0.0 - Enterprise DevOps Platform (October 1, 2025)

This release adds 12 new MCP tools transforming SSH Manager into a comprehensive DevOps automation platform:

💾 Backup & Restore System (4 tools)

• Automated backups for MySQL, PostgreSQL, MongoDB, and file systems
• Smart scheduling with cron integration and retention policies
• One-click restore with cross-database support
• *