内容
# SSH MCP 服务器
[](https://github.com/B143KC47/ssh_mcp/stargazers)
[](https://github.com/B143KC47/ssh_mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](https://www.openssh.com/)
**English** | [中文](README.zh-CN.md)
为 MCP 客户端提供安全的 SSH 访问。`ssh_mcp` 允许 Claude Desktop、VS Code Copilot、Augment 等 MCP 兼容的代理通过具有 OpenSSH 配置兼容性、连接池和输出防护的安全第一的 SSH 代理运行远程命令。
## 项目状态
- [贡献指南](CONTRIBUTING.md)
- [安全策略](SECURITY.md)
- [行为准则](CODE_OF_CONDUCT.md)
- [打开问题](https://github.com/B143KC47/ssh_mcp/issues)
- [查看 CI 运行](https://github.com/B143KC47/ssh_mcp/actions/workflows/ci.yml)
## 为什么开发者选择这个项目
- **使用您已经熟悉的 SSH 配置**：标准的 OpenSSH 字段，如 `Host`、`HostName`、`User`、`Port`、`IdentityFile` 和 `ProxyJump`
- **比原始 shell 桥接更安全**：内置的危险命令阻止、每主机允许列表/拒绝列表、输出上限和秘密隐藏
- **适用于多步骤代理会话的快速执行**：SSH 连接池减少了重新连接的开销
- **适用于真实的 MCP 工作流**：为 Claude Desktop、VS Code Copilot、Augment 和任何 MCP 兼容的客户端而设计
- **适用于团队的灵活性**：合并项目级和用户级配置，以便共享主机保持全局，而项目覆盖范围保持本地
## 适用场景
- AI 辅助的生产故障排除
- 远程服务器上的安全可观察性和只读操作
- DevOps 和平台工程 copilots
- 需要 SSH 访问但不授予代理无限 shell 自由的内部工具
## 快速入门
### 1. 安装和构建
```bash
npm install
npm run build
```
### 2. 将服务器添加到您的 MCP 客户端
参见以下示例：
- `examples/mcp-config.claude.example.json`
- `examples/mcp-config.vscode.example.json`
最小的 Claude Desktop / Augment 示例：
```json
{
"mcpServers": {
"ssh": {
"command": "node",
"args": [
"/绝对路径/到/ssh-mcp-server/dist/index.js",
"--project-root",
"/路径/到/您的/项目"
],
"env": {}
}
}
}
```
最小的 VS Code MCP 示例：
```json
{
"servers": {
"ssh": {
"command": "node",
"args": [
"/绝对路径/到/ssh-mcp-server/dist/index.js",
"--project-root",
"${workspaceFolder}"
]
}
}
}
```
### 3. 配置 SSH 主机
将 `examples/ssh.config.example` 复制到项目根目录下的 `ssh.config`，或通过 MCP 工具初始化：
```text
使用工具：ssh_init_config，作用域="project"
```
最小示例：
```sshconfig
Host my-server
HostName 192.168.1.100
User ubuntu
Port 22
IdentityFile ~/.ssh/id_rsa
# mcp-ssh:denylist = rm -rf,mkfs,dd,shutdown,reboot
```
### 4. 在您的 MCP 客户端中尝试几个提示
- "列出所有配置的 SSH 主机。"
- "测试与 `my-server` 的 SSH 连接。"
- "在 `my-server` 上运行 `uptime && df -h`。"
- "为 `my-server` 显示合并的 SSH 配置。"
## 核心功能
- **双范围配置**：项目级 (`ssh.config`) + 用户级 (`~/.config/mcp-ssh/config`) 自动合并
- **连接池**：在命令之间重用 SSH 连接并进行空闲清理
- **每主机安全策略**：允许列表、拒绝列表、最大超时时间和最大输出大小
- **输出管理**：自动截断以保护 LLM 上下文窗口
- **敏感数据保护**：私钥和敏感环境值在输出中被净化
- **OpenSSH 兼容性**：继续使用您的正常主机别名和 SSH 习惯
## 配置
### 配置文件位置
| 范围 | 路径 | 目的 |
|-------|------|---------|
| 项目 | `<project-root>/ssh.config` | 特定于当前项目的 SSH 主机 |
| 用户 | `~/.config/mcp-ssh/config` | 跨项目共享的 SSH 主机 |
**合并规则**：项目级设置覆盖用户级设置，适用于同名主机。
### 安全注解
在 `Host` 块内添加策略作为注释：
```sshconfig
# mcp-ssh:denylist = cmd1,cmd2 # 阻止这些命令模式
# mcp-ssh:allowlist = cmd1,cmd2 # 只允许这些命令模式
# mcp-ssh:maxTimeoutMs = 30000 # 此主机的最大执行超时
# mcp-ssh:maxOutputChars = 5000 # 此主机的最大输出字符数
```
### 身份验证顺序
1. `IdentityFile` 中的 **私钥**
2. 通过 `SSH_AUTH_SOCK` （Unix）或 Pageant（Windows）的 **SSH 代理**
3. 环境变量 `SSH_PASSWORD_<HOST>` 中的 **密码**
示例：对于主机 `my-server`，设置 `SSH_PASSWORD_MY_SERVER=secret`。
## 为什么它比普通的 SSH 包装器更好
| 普通远程执行桥接 | SSH MCP 服务器 |
|---|---|
| 通常会公开一个具有很少策略控制的完整 shell | 支持每主机允许列表/拒绝列表 |
| 为每个代理步骤重新连接 | 重用连接池 |
| 容易用巨大的输出溢出模型上下文 | 自动截断输出 |
| 自定义主机定义 | 与熟悉的 OpenSSH 配置语法配合使用 |
| 机密可能会泄漏到日志中 | 净化输出并隐藏敏感值 |
## MCP 工具
| 工具 | 描述 | 参数 |
|------|-------------|------------|
| `ssh_list_hosts` | 列出所有可用的 SSH 主机 | — |
| `ssh_exec` | 在远程主机上执行命令 | `host`、`command`、`timeout_ms?` |
| `ssh_init_config` | 初始化 SSH 配置文件 | `scope`、`project_root?`、`hosts?` |
| `ssh_get_config` | 获取特定主机的配置 | `host` |
| `ssh_test_connection` | 测试与主机的连接性 | `host` |
| `ssh_disconnect` | 断开与一个主机或所有活动会话的连接 | `host?` |
## MCP 资源
| URI | 描述 |
|-----|-------------|
| `ssh://hosts` | 所有配置的 SSH 主机的 JSON 列表 |
## 安全第一的默认设置
- 默认阻止 `rm -rf /`、`mkfs`、`dd if=`、`shutdown` 和 `reboot` 等危险命令
- 私钥材料和敏感环境值已从输出中隐藏
- 命令在执行前会进行净化
- 并发连接数和空闲寿命有限制
生产环境推荐：
1. 优先使用 `IdentityFile` 而非密码身份验证
2. 为生产主机使用 `# mcp-ssh:allowlist`
3. 如果 `ssh.config` 包含敏感主机名，请将其添加到 `.gitignore`
4. 在生产环境中启用 `--strict-host-key`
5. 在可能的情况下使用 SSH 证书或固定的 `known_hosts` 条目
## CLI 选项
```text
ssh-mcp-server [选项]
--project-root <path> 项目根目录（用于项目级 ssh.config）
--user-config <path> 自定义用户配置路径（默认：~/.config/mcp-ssh/config）
--strict-host-key 启用严格的主机密钥检查
--no-strict-host-key 禁用严格的主机密钥检查（默认）
--timeout <ms> 默认命令超时，单位为毫秒（默认：60000）
--max-output <chars> 每流的最大输出字符数（默认：10000）
--max-connections <n> 最大并发 SSH 连接数（默认：5）
--idle-timeout <ms> 连接空闲超时，单位为毫秒（默认：600000）
```
## 开发
```bash
# 安装依赖
npm install
# 以开发模式运行
npm run dev -- --project-root .
# 构建
npm run build
# 运行构建的服务器
npm start -- --project-root .
# 使用 MCP Inspector 进行调试
npm run inspect
```
## 贡献
欢迎提出问题和拉取请求。如果您希望支持更多 MCP 客户端、更强的 security 策略或更好的 SSH ergonomics，请提出问题并分享您想要启用的工作流。
有关贡献者工作流的详细信息，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 社区
- 请遵循 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 中的期望
- 对于安全问题，请使用 [SECURITY.md](SECURITY.md) 而不是提交公共错误报告
## License
MIT — 请参见 [LICENSE](LICENSE)。
