JinDaGe - ssh-hub MCP Details

article

README

🚀 ssh-hub

ssh-hub 是一个 MCP 服务器，它允许 AI 编码代理通过 SSH 完全访问远程机器。你可以同时连接到多个服务器，并通过 MCP 工具界面进行远程文件操作、执行 shell 命令以及目录同步。

🚀 快速开始

# 1. 添加远程服务器
ssh-hub add <SERVER_ALIAS> user@host

# 2. 在项目中注册为 MCP
ssh-hub mcp-install /path/to/project

连接字符串格式

user@host                  # 默认端口 22，路径为 ~
user@host:/path            # 显式指定路径
user@host:2222             # 自定义端口，路径为 ~
user@host:2222:/path       # 自定义端口和路径

身份文件

对于受密码短语保护的密钥，在 add 命令中使用 -i 参数 —— ssh-hub 会将密钥加载到你的 SSH 代理中：

注意：如果访问私钥需要密码短语，此命令将通过 ssh-add 询问密码短语并安全存储。

ssh-hub add <SERVER_ALIAS> user@host -i ~/.ssh/my_key

📦 安装指南

cargo install --git https://github.com/Perceptron-Studios/ssh-hub.git

升级

ssh-hub upgrade

💻 使用示例

基础用法

# 启动 MCP 服务器
ssh-hub

# 列出已配置的服务器
ssh-hub list

# 添加服务器
ssh-hub add <name> <connection>

# 从配置中移除服务器
ssh-hub remove <name>

# 更新服务器元数据和连接设置
ssh-hub update <name>

# 在项目中注册 ssh-hub 为 MCP 服务器
ssh-hub mcp-install [directory]

# 升级到最新版本
ssh-hub upgrade

高级用法

# 详细日志记录
ssh-hub -v

# 指定身份文件
ssh-hub add <name> <connection> -i <path>

# 覆盖端口
ssh-hub add <name> <connection> -p <port>

# mcp-install 仅生成 .mcp.json
ssh-hub mcp-install [directory] --claude

# mcp-install 仅生成 .codex/config.toml
ssh-hub mcp-install [directory] --codex

📚 详细文档

CLI 命令

| 命令 | 描述 | | ------------------------------- | ---------------------------------------------- | | ssh-hub | 在标准输入输出上启动 MCP 服务器（供 MCP 客户端使用） | | ssh-hub list | 列出已配置的服务器 | | ssh-hub add <name> <connection> | 添加服务器（测试连接后保存） | | ssh-hub remove <name> | 从配置中移除服务器 | | ssh-hub update <name> | 更新服务器元数据和连接设置 | | ssh-hub mcp-install [directory] | 在项目中注册 ssh-hub 为 MCP 服务器 | | ssh-hub upgrade | 升级到最新版本 |

选项： -v 详细日志记录，-i <path> 身份文件，-p <port> 端口覆盖。

mcp-install 标志： --claude（仅生成 .mcp.json），--codex（仅生成 .codex/config.toml）。默认两者都生成。

🔧 技术细节

身份验证

所有身份验证均基于 SSH 密钥。不存储或传输密码。密钥按以下顺序尝试：

身份文件 —— 在 add 命令中使用 -i 指定的密钥（优先级最高）
SSH 代理 —— 通过 ssh-add 加载的密钥，签名委托给 ssh-agent（最多 10 个密钥）
默认密钥 —— ~/.ssh/id_ed25519、id_rsa、id_ecdsa

RSA 密钥会自动与 SHA-256/SHA-512 签名进行协商（现代服务器拒绝旧的 SHA-1）。

MCP 工具

所有工具在首次使用时会自动连接到已配置的服务器，无需手动连接步骤。每个工具都接受一个 server 参数，引用已配置的服务器名称。

发现

list_servers —— 显示已配置的服务器，并进行实时可达性探测（TCP ping 并显示延迟）

远程操作

remote_bash —— 执行 shell 命令（可选超时和后台模式）
remote_read —— 读取文件内容（大文件可指定偏移量和限制）
remote_write —— 将内容写入文件
remote_edit —— 使用字符串替换编辑文件
remote_glob —— 查找匹配 glob 模式的文件

同步

sync_push —— 将本地文件或目录推送到远程（目录使用 tar 流传输）
sync_pull —— 将远程文件或目录拉取到本地（目录使用 tar 流传输）

配置

服务器配置存储在 ~/.config/ssh-hub/servers.toml（macOS：~/Library/Application Support/ssh-hub/servers.toml）：

[servers.staging]
host = "staging.example.com"
user = "deploy"
port = 2222
remote_path = "/var/www/app"
identity = "~/.ssh/id_staging"

[servers.prod]
host = "prod.example.com"
user = "deploy"
remote_path = "~"

📄 许可证

MIT

ssh-hub