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.8.5

🔒 Security release — three command-injection advisories fixed, one of which defeated readonly mode (Released: August 28, 2026)

Upgrade if you use ssh_backup_*, ssh_db_dump, ssh_service_status or ssh_tail — and especially if you rely on the readonly / restricted security modes.

• 🔴 RCE bypassing readonly / restricted (GHSA-m793-whw6-f537) — ssh_service_status and ssh_tail are read-only, so they stay enabled on servers you locked down, and neither quoted its arguments nor consulted the policy layer. A service name like nginx; id > /tmp/pwned executed. This defeated the exact control those modes exist to provide.
• 🔴 RCE through ssh_db_dump (GHSA-796j-h5q5-jx6p) — the stat command run after the dump interpolated the output path raw. The v3.6.7 patch had stopped one line short.
• 🟠 RCE through every ssh_backup_* tool (GHSA-qwwm-vrm9-4mw8) — backup-manager.js had zero shell escaping across its 9 builders, while database-manager.js had 95. The v3.6.7 fix was never extended to it.

The quoting helper now lives in one module (src/shell-quote.js) so "did this builder quote its inputs?" has a single answer, and a new test drives 340 builder × argument × payload combinations through a real shell to prove none of them execute.

Read full changelog →

---

🔐 Giving an agent SSH access, safely

An MCP SSH server is the most dangerous tool you can hand an AI agent: a shell on machines that matter. This one is built so you decide how far the agent can go — per server, not globally.

Mode	What the agent can do
unrestricted (default)	Everything. Same behaviour as any other SSH MCP server.
readonly	Mutating tools are refused outright — no deploy, no upload, no sudo, no database import. Read commands still work.
restricted	Every command must match an allow pattern and no deny pattern. Anything else is refused before it reaches the host.

SSH_SERVER_PROD_MODE=readonly
SSH_SERVER_STAGING_MODE=restricted
SSH_SERVER_STAGING_ALLOW_PATTERNS=^systemctl (status|restart) myapp$;^tail -n \d+ /var/log/

Alongside that:

• The sudo password never reaches the remote command line. It travels on the SSH channel's stdin, so it is not visible in ps, in /proc/<pid>/cmdline, or in an auditd trail — unlike the echo "$pass" | sudo -S pattern common in this category (#34).
• Every database argument is shell-quoted through one centralised helper, guarded by a 648-combination injection test.
• Read-only SQL is enforced, not suggested: ssh_db_query refuses anything that is not a SELECT.
• Vulnerabilities are published, not buried. See SECURITY.md for the reporting process and the advisories already fixed.
• Reproducible installs: the lockfile is committed, CI installs with npm ci, and a test enforces that every dependency resolves to registry.npmjs.org with an integrity hash and no unreviewed install scripts.

---

Previous Releases

v3.8.4 - Secrets stop reaching the log, CodeQL on every commit (August 28, 2026)

• 🔒 The logger no longer writes secrets in clear text — it writes to ~/.ssh-manager.log and stderr (which your MCP host captures), so one call site handing it a server config would have persisted a production password. Redaction now happens inside the logger. Also: CodeQL on every push, every action pinned by SHA, and a broken example that never parsed. Full changelog →

v3.8.2 / v3.8.3 - Sudo password leak fixed, MCP Registry, signed releases (August 28, 2026)

• 🔒 The sudo password no longer reaches the remote command line (#34) — it travelled through echo "<password>" | sudo -S, readable in ps and /proc/<pid>/cmdline by every account on the host. It now goes over the SSH channel's stdin. Also: listed in the official MCP Registry as io.github.bvisible/mcp-ssh-manager, releases published from CI with SLSA provenance and a CycloneDX SBOM, and the per-server security modes documented at last. Full changelog →

v3.8.1 - Reproducible installs and blocking quality gates (August 28, 2026)

• Committed lockfile (#60 — contributed by @cudatuda) plus npm run test:lockfile guarding it against drift and tampering. CI installs with npm ci; ESLint and the JSDoc typecheck became blocking gates after being purely decorative. Full changelog →

v3.8.0 - Groups in your config, ssh_sync on Windows, tunnel crash fix (August 14, 2026)

• 👥 New optional group field per server (#56 — contributed by @ice616, requested in #55) — tag a server with group = "production" and it is in that group: ssh_execute_group resolves members straight from your .env/TOML, union'd with any .server-groups.json you already keep. Also: ssh_sync fixed from a Windows host (#59 — contributed by @2836603852), a tunnel on a busy port no longer takes the whole MCP server down, the @modelcontextprotocol/sdk floor raised to ^1.30.0 over three advisories, and JSDoc type-checking added to CI. Full changelog →

v3.7.0 - Per-server SSH agent forwarding (July 13, 2026)

• 🔗 New opt-in FORWARD_AGENT / forward_agent option (#53 — requested by @raphaelbahat in #52) — the equivalent of OpenSSH's ForwardAgent yes, per server: processes on the remote host authenticate to other SSH hosts with the keys in your local ssh-agent, without copying any private key. Requires a running agent and defaults to false. Full changelog →

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)
• ⏱️ 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
• Metadata tracking for audit and compliance

🏥 Health & Monitoring (4 tools)

• Real-time health checks with CPU, RAM, Disk, and Network metrics
• Service monitoring for nginx, mysql, docker, and custom services
• Process management with CPU/RAM sorting and kill capabilities
• Alert thresholds with configurable notifications

🗄️ Database Management (4 tools)

• Safe database dumps with compression and selective exports
• Database imports with automatic decompression
• Schema exploration listing databases, tables, and collections
• Secure queries with SQL injection prevention (SELECT-only)

📊 Total: 37 MCP Tools | 🔧 ~4,100 Lines of Code Added | ✅ Production Ready

Read Full Changelog →

---

📑 Table of Contents

• Features
• Tool Management
• Prerequisites
• Quick Start - Claude Code
• Quick Start - OpenAI Codex
• Available MCP Tools
• Configuration
• Usage Examples
• Security
• Troubleshooting
• Known Limitations
• Contributing
• License

---

🌟 Features

Core Features

• 🔗 Multiple SSH Connections - Manage unlimited SSH servers from a single interface
• 🔐 Secure Authentication - Support for password, SSH key, and ssh-agent authentication (including passphrase-protected keys)
• 🔀 ProxyJump / Bastion Host - Connect to servers behind jump hosts with chained multi-hop support
• 🔌 ProxyCommand / Custom Proxy - Connect through SOCKS5 proxies or custom proxy commands (ncat, ssh -W, etc.)
• 📁 File Operations - Upload and download files between local and remote systems
• ⚡ Command Execution - Run commands on remote servers with working directory support
• 📂 Default Directories - Set default working directories per server for convenience
• 🎯 Easy Configuration - Simple .env file setup with guided configuration tool