mcp-ssh-manager

OpenAI Codex — 安装方式相同，然后配置两个文件。在 ~/.codex/config.toml 中：

[mcp_servers.ssh-manager]
command = "mcp-ssh-manager"
env = { SSH_CONFIG_PATH = "/Users/you/.codex/ssh-config.toml" }
startup_timeout_ms = 20000

然后在 ~/.codex/ssh-config.toml 中配置你的服务：

[ssh_servers.production]
host = "prod.example.com"
user = "admin"
key_path = "~/.ssh/id_rsa"
default_dir = "/var/www"
group = "production"

以下所有内容在 Codex 中的用法都完全相同 — 同样的 37 个工具，同样的配置字段。

从源代码安装：

git clone https://github.com/bvisible/mcp-ssh-manager.git
cd mcp-ssh-manager && npm install
cd cli && ./install.sh
claude mcp add ssh-manager node /absolute/path/to/mcp-ssh-manager/src/index.js

MCP 引擎无需构建。从检出目录使用界面（ssh-manager control），需先构建一次：npm run build:ui（已发布的软件包和桌面应用已包含该界面）。

作用范围 — --scope project 会写入团队可提交的 .mcp.json；--scope user 会为你在所有地方启用它。

先决条件 — Node 18+，支持 Linux、macOS 或 Windows。运行 ssh_sync 需要 rsync；仅在使用密码验证进行同步时才需要 sshpass（brew install hudochenkov/sshpass/sshpass，或 apt-get install sshpass）。

核心 — 始终启用

备份与恢复（v2.1+）

请参阅备份指南和 examples/backup-workflow.md。

健康状况与监控（v2.2+）

数据库（v2.3+）

部署与会话

组织管理

全部 37 个工具大约占用 43.5k tokens 的上下文。大多数人用不着全部工具。

ssh-manager tools configure     # interactive wizard
ssh-manager tools list          # what's on right now
ssh-manager tools enable monitoring
ssh-manager tools disable backup

工具组：core（5 个，始终启用）· sessions（4 个）· monitoring（6 个）· backup（4 个）· database（4 个）· advanced（14 个）。

工具更少，也意味着更少的审批提示和更快的启动速度。ssh-manager tools export-claude 会生成相应的自动审批配置块。

📖 完整指南 →

没人是从零开始的。你可能有包含 40 个主机的 ~/.ssh/config、FileZilla 站点管理器，或同事发来的电子表格。

ssh-manager import ~/.ssh/config          # the format is worked out for you
ssh-manager import --from transmit        # or read where a tool keeps its list
ssh-manager import --template servers.xlsx   # or get a form to fill in

两种可互换的格式由同一个加载器读取：.env 通常与 Claude Code 搭配使用，TOML 则与 Codex 搭配使用（从 SSH_CONFIG_PATH 或 ~/.codex/ssh-config.toml 读取）。两者可以共存，加载器会将它们合并。

SSH_SERVER_[NAME]_HOST=hostname_or_ip
SSH_SERVER_[NAME]_USER=username
SSH_SERVER_[NAME]_PASSWORD=password          # or use a key
SSH_SERVER_[NAME]_KEYPATH=~/.ssh/key
SSH_SERVER_[NAME]_CERTPATH=~/.ssh/key-cert.pub # optional: OpenSSH certificate for KEYPATH
SSH_SERVER_[NAME]_PASSPHRASE=key_passphrase  # optional
SSH_SERVER_[NAME]_PORT=22                    # optional
SSH_SERVER_[NAME]_DEFAULT_DIR=/var/www       # optional working directory
SSH_SERVER_[NAME]_SUDO_PASSWORD=…            # optional, for automated deploys
SSH_SERVER_[NAME]_DESCRIPTION=…              # optional
SSH_SERVER_[NAME]_GROUP=production           # optional, free-form label
SSH_SERVER_[NAME]_PLATFORM=windows           # optional: linux (default) | windows
SSH_SERVER_[NAME]_PROXYJUMP=bastion          # optional: another server, as jump host
SSH_SERVER_[NAME]_PROXYCOMMAND=…             # optional: ncat, ssh -W, …
SSH_SERVER_[NAME]_FORWARD_AGENT=true         # optional, and a real security trade-off
SSH_SERVER_[NAME]_ANNOUNCE_AGENT=true        # optional: tell this host an AI agent is driving (off by default)
SSH_SERVER_[NAME]_MODE=readonly              # optional: unrestricted | readonly | restricted
# Approval is NOT a field here — it is set per server from the control plane and
# stored in the vault, so that a shell on one of your machines cannot switch off
# the gate that exists to stop it.
SSH_SERVER_[NAME]_AUDIT_LOG=~/audit.jsonl    # optional JSONL trail

对应的 TOML 写法：

[ssh_servers.production]
host = "prod.example.com"
user = "admin"
key_path = "~/.ssh/id_rsa"
port = 22
default_dir = "/var/www"
group = "production"
description = "Production server"

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

[ssh_servers.internal]
host = "10.0.0.5"
user = "admin"
proxy_jump = "bastion"

OpenSSH 用户证书——对于信任证书颁发机构（TrustedUserCAKeys）的服务器，请将 CERTPATH / cert_path 指向为 KEYPATH 签发的证书（通常是 <key>-cert.pub）。每次连接时都会读取该文件，因此在磁盘上续期的短期证书无需重启；如果文件缺失，连接会失败，而不会回退到未签名的密钥。此功能将在 ssh2 支持证书后生效（mscdex/ssh2#1495）；在此之前，仍会像以往一样提供普通密钥。ssh_sync 使用系统的 ssh，它会自行查找密钥旁边的 <key>-cert.pub。

加载顺序按优先级从高到低排列：进程环境变量 → .env → 加密保险库 → TOML。你主动存入保险库的凭据优先于留在 .env 中的凭据；操作员为单次运行设置的覆盖值则优先于两者。

配置档案会按项目类型打包别名和钩子。使用 export SSH_MANAGER_PROFILE=frappe 设置配置档案，或者从助手中切换；助手会将其记在 ~/.ssh-manager/profile 中。内置 default、frappe、docker 和 nodejs；你可以在 profiles/ 中添加自己的配置档案。自定义别名和钩子也保存在 ~/.ssh-manager/ 中，因此升级后仍会保留。

更多示例：examples/codex-ssh-config.example.toml。

通过堡垒机——隧道是透明的，所有工具都能照常使用：

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

SSH_SERVER_PRIVATE_HOST=10.0.0.5
SSH_SERVER_PRIVATE_USER=admin
SSH_SERVER_PRIVATE_PROXYJUMP=bastion

支持串联：如果 bastion 本身配置了 PROXYJUMP，也会递归地跟随该配置。系统会检测并拒绝循环引用。

通过 SOCKS 代理或自定义命令——命令在本地运行并转发到主机，可使用 %h 和 %p 分别表示主机和端口：

SSH_SERVER_SOCKS_PROXYCOMMAND="ncat --proxy 127.0.0.1:1080 --proxy-type socks5 %h %p"
SSH_SERVER_WINPROXY_PROXYCOMMAND="C:\Windows\System32\OpenSSH\ssh.exe -W %h:%p user@jump-host"

受密码短语保护的密钥——将密钥加载到 ssh-agent 即可，无需其他操作；系统会自动使用 SSH_AUTH_SOCK，与普通 ssh 使用的机制相同。也可以在配置中存储 PASSPHRASE，但这不是理想做法。

Agent 转发（FORWARD_AGENT=true，默认关闭，按服务器配置）可让远程主机上的进程使用你的本地密钥向其他主机进行身份验证——例如，在服务器上通过 SSH 执行 git clone，而无需将私钥复制到服务器。

⚠️ 任何能够读取该主机上转发套接字的人——包括 root——都能在连接期间冒充你，访问其他主机。仅用于你信任的服务器；这与 ssh_config(5) 中的建议一致。 告知服务器有 Agent 正在操作（可为每台服务器设置 ANNOUNCE_AGENT=true，或为所有服务器设置 SSH_MANAGER_ANNOUNCE_AGENT=true；默认关闭）。随后，每个命令通道都会携带 AI_AGENT=mcp-ssh-manager，遵循 通过 SSH 传递 AI_AGENT 的约定，这样记录该值的主机就能区分由 Agent 操作的会话和由人员操作的会话——SSH 本身无法做到这一点：无论哪种情况，密钥和用户都相同。感谢 @mthamil107 在 #84 中贡献此功能。

• 服务器必须接受该值。 标准 OpenSSH 默认配置为 AcceptEnv LANG LC_*，并会静默丢弃其他所有值。将 AcceptEnv AI_AGENT 添加到 sshd_config 并重新加载；之后，Agent 运行的每条命令和每个 shell 都会设置 $AI_AGENT，供配置文件、封装脚本或审计钩子记录。
• 默认关闭，原因有二。 升级不能改变发送到服务器的内容。而且，无论服务器是否设置了 AcceptEnv，请求都会发送到每台主机——sshd 只是不保存该值——因此，不受你控制的主机会得知另一端有 Agent，还可能针对 Agent 调整输出。全局开关启用时，可设置 ANNOUNCE_AGENT=false 让某台主机保持静默。
• **适用范围：**命令、ssh_tail --follow、交互式会话，以及 ssh_sync（通过 SendEnv，OpenSSH 3.9 起支持）。**不适用范围：**SFTP 传输——如果服务器拒绝该变量，ssh2 会导致整个 SFTP 会话失败；以及端口转发，因为它没有环境变量。
• 绝不会告知服务器有人员正在操作。 你从控制平面执行的所有操作——shell、文件操作、健康检查或跨组命令——都由你执行，并且不会带标签地发送到服务器。

分组——为服务器添加标签，它们就会自动组成一个组，无需维护额外文件：

SSH_SERVER_WEB1_GROUP=production
SSH_SERVER_WEB2_GROUP=production

通过 ssh_group_manage 创建的组保存在 .server-groups.json 中，并且还会包含执行设置（策略、延迟、出错时停止）。当同名组同时存在于两处时，成员关系取并集，并使用已保存的设置。组名不区分大小写。仅通过 group 字段存在的组对于 ssh_group_manage 是只读的——请编辑服务器以更改成员关系。

Claude Code 卡住或显示“Interrupted”——几乎总是因为输出过大，超出上下文限制。输出会自动截断，默认超时时间为两分钟，但你可以调整：

MCP_SSH_MAX_OUTPUT_LENGTH=5000    # default 10000 characters
MCP_SSH_DEFAULT_TIMEOUT=180000    # default 120000 ms
MCP_SSH_COMPACT_JSON=true         # fewer tokens per response

与其使用 cat huge.log，不如优先使用 tail -n 100 huge.log——这也是你会给同事的建议。

工具没有显示——先运行 claude mcp list，然后重启 Claude Code。在 Claude Code 中使用 /mcp 可查看实时状态。

连接失败——先运行 ssh-manager server test <name>；它会告诉你问题出在 DNS、防火墙还是凭据。

权限被拒绝——检查 chmod 600 ~/.ssh/your_key，然后检查用户名，最后检查该用户在主机上获准执行的操作。

还是解决不了？提交问题——请附上服务器的 PLATFORM，以及 ssh-manager server test 的输出。

已知限制，如实说明：

• 命令超时只是建议。 ssh2 无法终止远程进程；在 Linux 和 macOS 主机上，timeout 封装脚本可以正确处理。Windows 主机上请设置 PLATFORM=windows 以跳过该封装脚本，因为 Windows 版 OpenSSH 无法识别它。
• 使用密码认证的 ssh_sync 需要 sshpass。 无论如何，密钥认证更好。在 Windows 主机上，请传入原生路径，例如 local:C:\project——盘符路径和 UNC 路径会转换为 MSYS2 格式；已经写成 /c/... 的路径则会原样传递，不会重复转换。
• 连接会被池化并重复使用。 过期连接会在下次使用时重新连接；可通过 ssh_connection_status 和 reconnect 操作强制重新连接。

git clone https://github.com/bvisible/mcp-ssh-manager.git
cd mcp-ssh-manager && npm ci
./scripts/setup-hooks.sh      # pre-commit checks, including secret detection

npm test                      # 43 suites
npm run typecheck             # JSDoc through tsc, no build step
npm run test:all              # both, plus ./scripts/validate.sh
npm run test:preview          # isolated candidate fixture, restart and cleanup

目录结构：

src/          index.js is the MCP server and its 37 tools; one module per domain
              (ssh-manager, config-loader, session-manager, backup-manager,
               health-monitor, database-manager, tunnel-manager, server-groups…)
cli/          the Bash CLI, plus the Node wrapper that makes it work on Windows
ui/           the control plane's React interface (v4)
desktop/      the Electron build (v4)
profiles/     frappe, docker, nodejs — and room for yours
scripts/      validation, and the rig that regenerates every screenshot and the video
docs/         guides, migration notes, security modes

欢迎提交 Pull Request——详情请见 CONTRIBUTING.md。桌面版的发布流程——签名、公证，以及为什么 Mac App Store 是一个不同的产品，而非更进一步的发布渠道——请见 docs/DISTRIBUTION.md。

本 README 中的图片没有一张是手工制作的。scripts/demo-env.mjs 会在回环地址上启动三个真实的 ssh2 服务，并预置一个保险库、一项待处理的审批和一个实时流；capture-screenshots.mjs 和 record-demo.mjs 会通过 DevTools 协议驱动 Chrome 与这些服务交互；frame-screenshots.py 会绘制浏览器和应用窗口，macbook-mockup.py 会绘制笔记本电脑。更改 UI 后，请重新运行这些脚本，不要直接编辑图片。

主视觉动画提供浅色和深色两个版本，并通过 <picture> 根据 prefers-color-scheme 切换。使用单个透明 GIF 会更简单，但 GIF 的 alpha 通道只有 1 位，而且透明度会影响帧间压缩：同一段动画使用透明背景时大小为 11.4 MB，而使用纯色背景时只有 357 KB。