MCP SSH管理

📋 Prerequisites

• Node.js (v18 or higher)
• npm (comes with Node.js)
• Platforms: Linux, macOS, Windows
• For Claude Code: Claude Code CLI installed
• For OpenAI Codex: Codex CLI configured
• Bash 4.0+ (for CLI management tools)
• rsync (for file synchronization)
• sshpass (optional, for rsync with password authentication)
• macOS: brew install hudochenkov/sshpass/sshpass
• Linux: apt-get install sshpass

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

Quick Setup

```bash

1. Install MCP SSH Manager

Option A: Install from npm (recommended)

```bash

Install globally from npm

npm install -g mcp-ssh-manager

Or install locally

npx mcp-ssh-manager

**Option B: Install from source**

Clone and install

git clone https://github.com/bvisible/mcp-ssh-manager.git cd mcp-ssh-manager npm install

Install the Bash CLI

cd cli && ./install.sh

2. Install to Claude Code

```bash

SSH_SERVER_CI_ALLOW_PATTERNS="^docker (ps|logs);^kubectl get "

```

• unrestricted (default, no field needed) — identical to pre-v3.5.0 behavior. Zero overhead.
• readonly — blocks ssh_upload, ssh_deploy, ssh_sync, ssh_execute_sudo, backup/db write tools, and built-in destructive commands (rm, mv, sudo, systemctl restart, redirects outside /tmp, curl | sh, …).
• restricted — every ssh_execute command must match at least one ALLOW_PATTERNS regex AND no DENY_PATTERNS regex.

Existing configs are unaffected — no field is mandatory, no behavior changes unless you opt in. See docs/SECURITY_MODES.md for the full reference, recipes, and limitations.

1. Install MCP SSH Manager

Same installation as Claude Code (see above), then configure for Codex:

```bash

Deployment Tools (v1.2+)

#### ssh_deploy 🚀 Deploy files with automatic permission and backup handling. - Parameters: server, files (array), options (owner, permissions, backup, restart) - Automatically handles permission issues and creates backups

#### ssh_execute_sudo 🔐 Execute commands with sudo privileges. - Parameters: server, command, password (optional), cwd (optional) - Securely handles sudo password without exposing in logs

Verify MCP Installation

claude mcp list

Development Setup

1. Fork the repository 2. Clone and install dependencies 3. Setup pre-commit hooks for code quality:

   ./scripts/setup-hooks.sh
   

🎯 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

🚀 Quick Start - Claude Code

🚀 Quick Start - OpenAI Codex

Example: Linux server

SSH_SERVER_PRODUCTION_HOST=prod.example.com SSH_SERVER_PRODUCTION_USER=admin SSH_SERVER_PRODUCTION_PASSWORD=secure_password SSH_SERVER_PRODUCTION_PORT=22 SSH_SERVER_PRODUCTION_DEFAULT_DIR=/var/www/html SSH_SERVER_PRODUCTION_DESCRIPTION=Production Server SSH_SERVER_PRODUCTION_SUDO_PASSWORD=secure_sudo_pass # Optional, for automated deployments

Example: Windows server (OpenSSH for Windows)

SSH_SERVER_WINHOST_HOST=192.168.1.90 SSH_SERVER_WINHOST_USER=svc-ssh SSH_SERVER_WINHOST_KEYPATH=~/.ssh/winhost_key SSH_SERVER_WINHOST_PORT=2222 SSH_SERVER_WINHOST_PLATFORM=windows SSH_SERVER_WINHOST_DESCRIPTION=Windows host via OpenSSH

Example: Server behind a bastion/jump host

SSH_SERVER_BASTION_HOST=bastion.example.com SSH_SERVER_BASTION_USER=jumpuser SSH_SERVER_BASTION_KEYPATH=~/.ssh/bastion_key

SSH_SERVER_INTERNAL_HOST=10.0.0.5 SSH_SERVER_INTERNAL_USER=admin SSH_SERVER_INTERNAL_KEYPATH=~/.ssh/internal_key SSH_SERVER_INTERNAL_PROXYJUMP=bastion SSH_SERVER_INTERNAL_DESCRIPTION=Private server behind bastion ```

📚 Advanced Usage

📚 Usage Examples

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 →

Interactive configuration wizard

ssh-manager tools configure

View current configuration

ssh-manager tools list

Configuration Modes

Configure your first server

ssh-manager server add ```

3. Configure Auto-Approval (Optional but Recommended)

To avoid being prompted for approval on every SSH command, add auto-approve configuration:

Edit ~/.config/claude-code/claude_code_config.json:

{
  "mcpServers": {
    "ssh-manager": {
      "command": "node",
      "args": ["/path/to/mcp-ssh-manager/src/index.js"],
      "autoApprove": [
        "mcp__ssh-manager__ssh_execute",
        "mcp__ssh-manager__ssh_list_servers",
        "mcp__ssh-manager__ssh_upload",
        "mcp__ssh-manager__ssh_download",
        "mcp__ssh-manager__ssh_sync",
        "mcp__ssh-manager__ssh_alias"
      ]
    }
  }
}

Important: Restart Claude Code after making this change.

For full auto-approval of all SSH tools, see the complete list in examples/claude-code-config.example.json.

3.5. Security Modes (Optional, v3.5.0+)

autoApprove is all-or-nothing per tool: once ssh_execute is approved, anything goes. If you want a second layer that filters what the MCP server actually accepts to run — useful when sharing the MCP with a third-party agent, a CI bot, or a client's server — declare a per-server security mode.

```bash

In your .env — three optional fields. Omit them all to keep v3.4.x behavior exactly.

SSH_SERVER_CLIENT_PROD_HOST=client-prod.example.com SSH_SERVER_CLIENT_PROD_USER=consultant SSH_SERVER_CLIENT_PROD_KEYPATH=~/.ssh/consultant_ed25519

SSH_SERVER_CLIENT_PROD_MODE=readonly # unrestricted | readonly | restricted SSH_SERVER_CLIENT_PROD_AUDIT_LOG=~/.ssh-manager/audit.jsonl # opt-in JSONL audit trail

Migrate existing servers to TOML format (if you have .env servers)

ssh-manager codex migrate

2. Manual Configuration (Optional)

If you prefer manual setup, add to ~/.codex/config.toml:

[mcp_servers.ssh-manager]
command = "node"
args = ["/absolute/path/to/mcp-ssh-manager/src/index.js"]
env = { SSH_CONFIG_PATH = "/Users/you/.codex/ssh-config.toml" }
startup_timeout_ms = 20000

3. Configure Servers in TOML Format

Create or edit ~/.codex/ssh-config.toml:

[ssh_servers.production]
host = "prod.example.com"
user = "admin"
password = "secure_password"  # or use key_path
key_path = "~/.ssh/id_rsa"   # for SSH key auth (recommended)
passphrase = "key_passphrase" # optional, for passphrase-protected keys
port = 22
default_dir = "/var/www"
description = "Production server"

[ssh_servers.staging]
host = "staging.example.com"
user = "deploy"
key_path = "~/.ssh/staging_key"
port = 2222
default_dir = "/home/deploy/app"

[ssh_servers.winhost]
host = "192.168.1.90"
user = "svc-ssh"
key_path = "~/.ssh/winhost_key"
port = 2222
platform = "windows"
description = "Windows host via OpenSSH"

[ssh_servers.bastion]
host = "bastion.example.com"
user = "jumpuser"
key_path = "~/.ssh/bastion_key"

[ssh_servers.internal]
host = "10.0.0.5"
user = "admin"
key_path = "~/.ssh/internal_key"
proxy_jump = "bastion"
description = "Private server behind bastion"

💡 See examples/codex-ssh-config.example.toml for more complete examples!

Convert .env to TOML (for Codex)

ssh-manager codex convert to-toml

Convert TOML back to .env (for Claude Code)

ssh-manager codex convert to-env ```

Both formats can coexist! The system supports both simultaneously.

---

🔧 Configuration

Environment Variables

Servers are configured in the .env file with this pattern:

```env

Server configuration pattern

SSH_SERVER_[NAME]_HOST=hostname_or_ip SSH_SERVER_[NAME]_USER=username SSH_SERVER_[NAME]_PASSWORD=password # For password auth SSH_SERVER_[NAME]_KEYPATH=~/.ssh/key # For SSH key auth SSH_SERVER_[NAME]_PASSPHRASE=key_passphrase # Optional, for passphrase-protected keys SSH_SERVER_[NAME]_PORT=22 # Optional, defaults to 22 SSH_SERVER_[NAME]_DEFAULT_DIR=/path/to/dir # Optional, default working directory SSH_SERVER_[NAME]_DESCRIPTION=Description # Optional SSH_SERVER_[NAME]_PLATFORM=windows # Optional: "linux" (default) or "windows" SSH_SERVER_[NAME]_PROXYJUMP=bastion # Optional: name of another server to use as jump host SSH_SERVER_[NAME]_PROXYCOMMAND=command # Optional: custom proxy command (ncat, ssh -W, etc.)

Set up Codex integration

ssh-manager codex setup

Test the integration

ssh-manager codex test ```

🐛 Troubleshooting