使用说明
SSH MCP服务器
英语 | 中文
MCP客户端的安全SSH访问。 ssh_mcp 允许Claude Desktop、VS Code Copilot、Augment和其他MCP兼容代理通过具有OpenSSH配置兼容性、连接池和输出护栏的安全第一SSH代理运行远程命令。
项目健康状况
为什么开发人员选择这个项目
- 使用您已经知道的SSH配置：标准OpenSSH字段，如
Host,HostName,User,Port,IdentityFile，以及ProxyJump - 比未加工的贝壳桥更安全：内置危险命令阻止、按主机分配列表/拒绝列表、输出上限和秘密编辑
- 快速进行多步骤代理会话：池化SSH连接减少了重新连接的开销
- 适用于真实的MCP工作流程：专为Claude Desktop、VS Code Copilot、Augment和任何兼容MCP的客户端而设计
- 团队灵活：合并项目级和用户级配置，使共享主机保持全局状态，而项目覆盖保持本地状态
非常适合
- 人工智能辅助生产故障排除
- 远程服务器上的安全可观察性和只读操作
- DevOps和平台工程副产品
- 需要SSH访问而无需向代理提供无限shell自由的内部工具
快速开始
1.安装和构建
npm install
npm run build
2.将服务器添加到MCP客户端
请参阅中的现成复制示例：
examples/mcp-config.claude.example.jsonexamples/mcp-config.vscode.example.json
最小克劳德桌面/增强示例：
{
"mcpServers": {
"ssh": {
"command": "node",
"args": [
"/absolute/path/to/ssh-mcp-server/dist/index.js",
"--project-root",
"/path/to/your/project"
],
"env": {}
}
}
}
最小VS代码MCP示例：
{
"servers": {
"ssh": {
"command": "node",
"args": [
"/absolute/path/to/ssh-mcp-server/dist/index.js",
"--project-root",
"${workspaceFolder}"
]
}
}
}
3.配置SSH主机
复制 examples/ssh.config.example 到 ssh.config 在您的项目根目录中，或通过MCP工具初始化一个：
Use tool: ssh_init_config with scope="project"
最小示例：
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主机。”
- “测试SSH连接到
my-server." - “跑
uptime && df -h上my-server." - “显示合并的SSH配置
my-server."
核心功能
- 双作用域配置：项目级别(
ssh.config)+用户级别(~/.config/mcp-ssh/config)自动合并 - 连接池：通过空闲清理跨命令重用SSH连接
- 每台主机的安全策略：允许列表、拒绝列表、最大超时和最大输出大小
- 输出管理：自动截断以保护LLM上下文窗口
- 敏感数据保护：私钥和敏感环境值在输出中被净化
- OpenSSH兼容性：继续使用正常的主机别名和SSH习惯
配置
配置文件位置
| 范围 | 路径 | 目的 |
|---|---|---|
| 项目 | <project-root>/ssh.config |
特定于当前项目的主机 |
| 用户 | ~/.config/mcp-ssh/config |
跨项目共享主机 |
合并规则：项目级设置会覆盖同名主机的用户级设置。
安全注解
将策略作为注释添加到 Host 块：
# mcp-ssh:denylist = cmd1,cmd2 # Block these command patterns
# mcp-ssh:allowlist = cmd1,cmd2 # Only allow these command patterns
# mcp-ssh:maxTimeoutMs = 30000 # Max execution timeout for this host
# mcp-ssh:maxOutputChars = 5000 # Max output characters for this host
身份验证顺序
- 私钥 从
IdentityFile - SSH代理 通过
SSH_AUTH_SOCK（Unix）或Pageant（Windows） - 密码 通过环境变量
SSH_PASSWORD_<HOST>
示例：用于主机 my-server，set SSH_PASSWORD_MY_SERVER=secret.
为什么这比普通的SSH包装器更好
| 普通远程执行桥 | SSH MCP服务器 |
|---|---|
| 经常暴露一个几乎没有策略控制的完整shell | 支持每台主机的allowlists/denylists |
| 为每个代理步骤重新连接 | 重用池连接 |
| 容易溢出具有大量输出的模型上下文 | 自动截断输出 |
| 自定义主机定义 | 使用熟悉的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默认情况下被阻止 - 从输出中编辑私钥材料和敏感环境值
- 命令在执行前经过净化
- 并发连接数和空闲寿命有限
建议用于生产：
- 更喜欢
IdentityFile通过密码验证 - 使用
# mcp-ssh:allowlist对于生产主机 - 添加
ssh.config到.gitignore如果它包含敏感的主机名 - 启用
--strict-host-key生产中 - 使用SSH证书或固定
known_hosts尽可能输入
CLI选项
ssh-mcp-server [options]
--project-root <path> Project root directory (for project-level ssh.config)
--user-config <path> Custom user config path (default: ~/.config/mcp-ssh/config)
--strict-host-key Enable strict host key checking
--no-strict-host-key Disable strict host key checking (default)
--timeout <ms> Default command timeout in ms (default: 60000)
--max-output <chars> Maximum output characters per stream (default: 10000)
--max-connections <n> Maximum concurrent SSH connections (default: 5)
--idle-timeout <ms> Connection idle timeout in ms (default: 600000)
发展
# Install dependencies
npm install
# Run in dev mode
npm run dev -- --project-root .
# Build
npm run build
# Run the built server
npm start -- --project-root .
# Debug with MCP Inspector
npm run inspect
贡献
欢迎问题和拉取请求。如果您希望支持更多的MCP客户端、更强大的安全策略或更好的SSH人体工程学，请打开一个问题并共享您想要启用的工作流程。
有关贡献者工作流程的详细信息，请参阅 贡献.md.
社区
- 请遵循以下期望 代码_OF_CONDUCT.md
- 对于安全问题，请使用 安全.md 而不是提交公开的bug报告
许可证
麻省理工学院——见 许可证.
