MCP SSH 管理器 - 通过模型上下文协议 (MCP) 进行 SSH 远程服务器管理 🚀

一个模型上下文协议 (MCP) 服务器，使 Claude Code 和 OpenAI Codex 能够管理多个 SSH 连接。直接从您的 AI 助手执行命令、传输文件、管理数据库、创建备份、监控健康状况并自动化服务器上的 DevOps 任务。

🎉 v3.2.2 版本更新内容

全局安装修复与 CLI 二进制文件（发布日期：2026 年 4 月 7 日）

• 🔧 全局安装修复：.env 路径解析现在使用回退链而不是硬编码的 __dirname — 可与 npm install -g 正确配合使用 (#16, #19)

  • 回退链：~/.ssh-manager/.env → cwd/.env → ~/.env → 项目 .env

  • 在首次执行 ssh-manager server add 时自动创建 ~/.ssh-manager/.env

• 📦 ssh-manager CLI 注册为二进制文件：npm install -g 现在会同时创建 mcp-ssh-manager 和 ssh-manager 命令 (#18)

• ⚡ 竞态条件修复：服务器配置现在在 MCP 服务器接受请求之前已完全加载

Related MCP server: MCP Server for FTP Access

历史版本

v3.2.0 - ProxyJump / 跳板机支持（2026 年 3 月 18 日）

• 🔀 ProxyJump 支持：通过简单的 PROXYJUMP 配置字段连接到堡垒机/跳板机后的服务器 (#15)

  • 通过递归连接链接多个跳转 (A → B → C)

  • 循环依赖检测可防止无限循环

  • 所有工具均可通过跳板机透明工作

• 📦 npx 支持修复：npx mcp-ssh-manager 现在可以正常工作 (#14)

v3.1.5 - SSH Agent 与密码短语支持（2026 年 3 月 5 日）

• 🔑 SSH Agent 支持：当 SSH_AUTH_SOCK 可用时自动使用 ssh-agent — 受密码短语保护的密钥可透明使用

• 🔐 密码短语配置：.env 和 TOML 格式均新增 passphrase 字段

感谢 @snjax 的原始贡献 (#12)。

v3.1.4 - Windows SSH 主机支持（2026 年 2 月 22 日）

• 🪟 Windows SSH 主机修复：命令在运行 OpenSSH 的 Windows 主机上不再失败 (#10)

• 新增每个服务器的 platform 配置字段（SSH_SERVER_FOO_PLATFORM=windows 或 TOML 中的 platform = "windows"）

• 当 platform=windows 时，跳过 Linux 的 timeout/sh -c 命令包装器，改用 SSH 库的原生超时设置

• 所有工具（ssh_execute, ssh_tail, ssh_monitor, ssh_deploy, ssh_execute_sudo, ssh_group_execute）均具备平台感知能力

v3.1.2 - Windows 兼容性修复（2026 年 2 月 9 日）

• 🪟 Windows 支持：修复了 Windows 上 process.env.HOME 未定义导致的崩溃 (#8)

• 现在使用 os.homedir() 以实现跨平台兼容性（Linux、macOS、Windows）

v3.1.0 - 工具激活系统（2025 年 11 月 15 日）

🎯 上下文使用优化

• 92% 上下文缩减：仅启用您需要的工具（最小模式：5 个工具 vs 全部 37 个）

• 工具管理 CLI：ssh-manager tools list/configure/enable/disable

• 6 个工具组：核心、会话、监控、备份、数据库、高级

• 自动批准导出：生成 Claude Code 自动批准配置

v3.0.0 - 企业级 DevOps 平台（2025 年 10 月 1 日）

此版本新增 12 个 MCP 工具，将 SSH 管理器转变为一个全面的 DevOps 自动化平台：

💾 备份与恢复系统（4 个工具）

• 自动备份：支持 MySQL、PostgreSQL、MongoDB 和文件系统

• 智能调度：集成 cron 和保留策略

• 一键恢复：支持跨数据库恢复

• 元数据跟踪：用于审计和合规性

🏥 健康与监控（4 个工具）

• 实时健康检查：包含 CPU、内存、磁盘和网络指标

• 服务监控：支持 nginx、mysql、docker 和自定义服务

• 进程管理：支持按 CPU/内存排序和终止进程

• 警报阈值：支持可配置的通知

🗄️ 数据库管理（4 个工具）

• 安全数据库转储：支持压缩和选择性导出

• 数据库导入：支持自动解压

• 模式探索：列出数据库、表和集合

• 安全查询：防止 SQL 注入（仅限 SELECT）

📊 总计：37 个 MCP 工具 | 🔧 新增约 4,100 行代码 | ✅ 生产就绪

阅读完整更新日志 →

📑 目录

• 功能

• 工具管理

• 先决条件

• 快速入门 - Claude Code

• 快速入门 - OpenAI Codex

• 可用 MCP 工具

• 配置

• 使用示例

• 安全性

• 故障排除

• 已知限制

• 贡献

• 许可证

🌟 功能

核心功能

• 🔗 多 SSH 连接 - 从单个界面管理无限数量的 SSH 服务器

• 🔐 安全身份验证 - 支持密码、SSH 密钥和 ssh-agent 身份验证（包括受密码短语保护的密钥）

• 🔀 ProxyJump / 跳板机 - 通过链式多跳支持连接到跳板机后的服务器

• 📁 文件操作 - 在本地和远程系统之间上传和下载文件

• ⚡ 命令执行 - 在远程服务器上运行命令，支持工作目录

• 📂 默认目录 - 为每个服务器设置默认工作目录，方便使用

• 🎯 简易配置 - 通过引导式配置工具进行简单的 .env 文件设置

企业级 DevOps 功能 (v3.0) 🎉

• 💾 备份与恢复 - MySQL、PostgreSQL、MongoDB 和文件的自动备份

• 🏥 健康监控 - 实时服务器健康检查（CPU、内存、磁盘、服务）

• 🗄️ 数据库管理 - 具备 SQL 注入防护的安全数据库操作

• 📊 进程管理 - 监控和控制服务器进程

• ⚠️ 智能警报 - 可配置的健康阈值和通知

v2.0 功能

• 🚀 Bash CLI - 用于服务器管理的极速纯 Bash CLI

• 📊 高级日志记录 - 包含级别和历史记录的全面日志系统

• 🔄 Rsync 集成 - 支持 rsync 的双向文件同步

• 💻 持久会话 - 在多个命令之间保持 shell 上下文

• 👥 服务器组 - 同时在多个服务器上执行命令

• 🔧 SSH 隧道 - 本地/远程端口转发和 SOCKS 代理支持

• 📈 系统监控 - CPU、内存、磁盘和网络的实时监控

• 🏷️ 服务器别名 - 使用短别名代替完整的服务器名称

• 🚀 智能部署 - 具备权限处理的自动化文件部署

• 🔑 Sudo 支持 - 安全地以 sudo 权限执行命令

• 📝 OpenAI Codex 支持 - 通过 TOML 配置与 OpenAI Codex 兼容

⚙️ 工具管理与上下文优化

v3.1 新增：通过工具激活管理，将 Claude Code 的上下文使用量减少 92%！

MCP SSH 管理器包含 37 个工具，分为 6 个组。默认情况下，所有工具均已启用，但您可以针对特定工作流程进行优化：

快速设置

# Interactive configuration wizard
ssh-manager tools configure

# View current configuration
ssh-manager tools list

# Enable/disable specific groups
ssh-manager tools enable monitoring
ssh-manager tools disable backup

配置模式

工具组

• 核心 (5 个工具) - 始终启用：列表、执行、上传、下载、同步

• 会话 (4 个工具) - 持久 SSH 会话

• 监控 (6 个工具) - 健康检查、服务状态、进程管理

• 备份 (4 个工具) - 数据库和文件备份

• 数据库 (4 个工具) - MySQL、PostgreSQL、MongoDB 操作

• 高级 (14 个工具) - 部署、sudo、隧道、组、别名等

优势

• 最小模式下 92% 的上下文缩减（节省约 40k tokens）

• Claude Code 中更少的批准提示

• 更快的加载速度和更简洁的界面

• 为 Claude Code 导出自动批准配置

📖 完整工具管理指南 →

📋 先决条件

• Node.js (v18 或更高版本)

• npm (随 Node.js 一起安装)

• 平台：Linux、macOS、Windows

• 对于 Claude Code：已安装 Claude Code CLI

• 对于 OpenAI Codex：已配置 Codex CLI

• Bash 4.0+ (用于 CLI 管理工具)

• rsync (用于文件同步)

• sshpass (可选，用于密码身份验证的 rsync)

  • macOS: brew install hudochenkov/sshpass/sshpass

  • Linux: apt-get install sshpass

🚀 快速入门 - Claude Code

1. 安装 MCP SSH 管理器

选项 A：从 npm 安装（推荐）

# Install globally from npm
npm install -g mcp-ssh-manager

# Or install locally
npx mcp-ssh-manager

选项 B：从源码安装

# 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

# Configure your first server
ssh-manager server add

2. 安装到 Claude Code

# For personal use (current user only)
claude mcp add ssh-manager node /path/to/mcp-ssh-manager/src/index.js

# For team sharing (creates .mcp.json in project)
claude mcp add ssh-manager --scope project node /path/to/mcp-ssh-manager/src/index.js

# For all your projects
claude mcp add ssh-manager --scope user node /path/to/mcp-ssh-manager/src/index.js

3. 配置自动批准（可选但推荐）

为避免在每个 SSH 命令上都被提示批准，请添加自动批准配置：

编辑 ~/.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"
      ]
    }
  }
}

重要：进行此更改后请重启 Claude Code。

如需对所有 SSH 工具进行完全自动批准，请参阅 examples/claude-code-config.example.json 中的完整列表。

4. 开始使用！

在 Claude Code 中，您现在可以：

"List all my SSH servers"
"Execute 'ls -la' on production server"  # Uses default directory if set
"Run 'docker ps' on staging"
"Upload config.json to production:/etc/app/config.json"
"Download logs from staging:/var/log/app.log"

使用默认目录： 如果您将 /var/www/html 设置为生产环境的默认目录，以下命令是等效的：

• "Run 'ls' on production" → 在 /var/www/html 中执行

• "Run 'ls' on production in /tmp" → 在 /tmp 中执行（覆盖默认值）

🚀 快速入门 - OpenAI Codex

1. 安装 MCP SSH 管理器

安装方式与 Claude Code 相同（见上文），然后为 Codex 进行配置：

# Set up Codex integration
ssh-manager codex setup

# Migrate existing servers to TOML format (if you have .env servers)
ssh-manager codex migrate

# Test the integration
ssh-manager codex test

2. 手动配置（可选）

如果您更喜欢手动设置，请添加到 ~/.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. 以 TOML 格式配置服务器

创建或编辑 ~/.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"

💡 查看 examples/codex-ssh-config.example.toml 获取更完整的示例！

4. 在 Codex 中开始使用！

在 OpenAI Codex 中，您现在可以：

"List my SSH servers"
"Execute 'docker ps' on production"
"Upload file.txt to staging:/tmp/"
"Monitor CPU usage on all servers"
"Download production:/var/log/app.log to ./logs/"

在格式之间转换

在 Claude Code (.env) 和 Codex (TOML) 之间轻松切换：

# 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

两种格式可以共存！系统同时支持两者。

🛠️ 可用 MCP 工具

核心工具

ssh_list_servers

列出所有已配置的 SSH 服务器及其详细信息。

ssh_execute

在远程服务器上执行命令。

• 参数：server (名称), command, cwd (可选工作目录)

• 注意：如果未提供 cwd，则使用服务器的默认目录（如果已配置）

`ssh_