内容
[](https://www.npmjs.com/package/ssh-mcp-pro)
[](LICENSE)
[](https://github.com/oaslananka/ssh-mcp-pro/actions/workflows/ci.yml)
[](https://oaslananka.github.io/ssh-mcp-pro/)
[](https://securityscorecards.dev/viewer/?uri=github.com/oaslananka/ssh-mcp-pro)
# ssh-mcp-pro
<p align="center">
<a href="https://www.buymeacoffee.com/oaslananka">
<img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=%E2%98%95&slug=oaslananka&button_colour=FFDD00&font_colour=000000&font_family=Arial&outline_colour=000000&coffee_colour=ffffff" alt="给我买杯咖啡" />
</a>
</p>
ssh-mcp-pro 是一个安全的模型上下文协议（MCP）服务器，用于 SSH 自动化。它允许支持 MCP 的客户端打开 SSH 会话、检查主机、运行受控命令、管理文件、传输工件、创建隧道，并通过策略控制的工具执行幂等包或服务工作。
## 前提条件
- Node.js `>=22.22.2` 或 `>=24.15.0` 或 `>=26.3.0`
- pnpm `>=11.0.9`
- SSH 访问目标主机
- Docker，仅用于本地集成测试和容器镜像构建
## 安装
使用 pnpm 全局安装：
```bash
pnpm add --global ssh-mcp-pro
ssh-mcp-pro --version
```
在没有全局安装的情况下运行：
```bash
npx ssh-mcp-pro
```
对于仅限 pnpm 的环境，请使用：
```bash
pnpm dlx ssh-mcp-pro
```
容器镜像发布到 GitHub 容器注册表中，版本号为：
```bash
docker run --rm ghcr.io/oaslananka/ssh-mcp-pro:1.0.0 --version
```
镜像发布到 `linux/amd64` 和 `linux/arm64`，具有确切的 semver 和 Git 标签别名。生产部署应优先使用发布工作流记录的摘要固定引用。有关标签策略、摘要固定示例和注册表验证步骤，请参阅 [Docker 使用](docs/docker.md)。
## 快速入门
通用 stdio MCP 配置：
```json
{
"name": "ssh-mcp-pro",
"command": "ssh-mcp-pro",
"type": "stdio"
}
```
VS Code 设置样式：
```json
{
"mcp.servers": {
"ssh-mcp-pro": {
"type": "stdio",
"command": "ssh-mcp-pro",
"args": []
}
}
}
```
Claude Desktop 样式：
```json
{
"mcpServers": {
"ssh-mcp-pro": {
"command": "ssh-mcp-pro",
"args": []
}
}
}
```
注册后，使用发现和严格的主机密钥策略启动：
```text
列出配置的 SSH 主机，以 deploy 身份打开到 bastion.example.com 的会话，hostKeyPolicy=strict，然后运行 os_detect。
```
## 用法
从 MCP 客户端通过 stdio 使用 ssh-mcp-pro，或为远程安全的连接器配置文件运行 HTTP 传输。首先使用只读发现工具，检查活动策略，并在运行远程命令之前创建显式会话：
```text
列出配置的 SSH 主机，解释活动 SSH 策略，连接到选定的主机，然后报告其操作系统和磁盘使用情况。
```
有关其他工作流程，请参阅 [examples/README.md](examples/README.md)，有关客户端特定设置的详细信息，请参阅 [INSTALL.md](INSTALL.md)。
## 配置
`src/config.ts` 解析的所有 `SSH_MCP_*` 环境变量如下所列。逗号分隔的设置也接受换行分隔值。
| 变量 | 默认值 | 目的 |
| --- | --- | --- |
| `SSH_MCP_MAX_SESSIONS` | `20` | 最大并发 SSH 会话数。 |
| `SSH_MCP_SESSION_TTL` | `900000` | 会话存活时间，毫秒。 |
| `SSH_MCP_COMMAND_TIMEOUT` | `30000` | 默认远程命令超时，毫秒。 |
| `SSH_MCP_MAX_COMMAND_OUTPUT_BYTES` | `1048576` | 每个命令结果的最大缓冲 stdout/stderr 字节数。 |
| `SSH_MCP_MAX_STREAM_CHUNKS` | `4096` | 最大保留流式传输块数。 |
| `SSH_MCP_MAX_FILE_SIZE` | `10485760` | 文本聚焦的文件读取返回的最大字节数。 |
| `SSH_MCP_MAX_FILE_WRITE_BYTES` | `10485760` | 缓冲前最大接受的写入有效负载。 |
| `SSH_MCP_MAX_TRANSFER_BYTES` | `52428800` | 最大上传或下载传输大小。 |
| `SSH_MCP_DEBUG` | `false` | 启用调试配置行为。 |
| `SSH_MCP_RATE_LIMIT` | `true` | 启用全局 MCP 请求速率限制器。 |
| `SSH_MCP_RATE_LIMIT_MAX` | `100` | 速率限制窗口的最大请求数。 |
| `SSH_MCP_RATE_LIMIT_PER_SESSION` | `true` | 当工具参数包含 `sessionId` 时，启用每个会话的 MCP 请求速率限制。 |
| `SSH_MCP_RATE_LIMIT_PER_SESSION_MAX` | `50` | 每个 SSH 会话每个速率限制窗口的最大请求数。 |
| `SSH_MCP_RATE_LIMIT_PER_SESSION_WINDOW_MS` | `60000` | 每个会话的速率限制窗口，毫秒。 |
| `SSH_MCP_RATE_LIMIT_WINDOW_MS` | `60000` | 速率限制窗口，毫秒。 |
| `SSH_MCP_STRICT_HOST_KEY` | 未设置 | 严格 vs 不安全的 host-key 检查的旧式布尔别名。 |
| `SSH_MCP_HOST_KEY_POLICY` | `strict` | host-key 模式：`strict`、`accept-new` 或 `insecure`。 |
| `SSH_MCP_KNOWN_HOSTS_PATH` | `~/.ssh/known_hosts` | 用于严格 host-key 验证的已知主机文件。 |
| `SSH_MCP_ALLOW_ROOT_LOGIN` | `false` | 允许 SSH 以 root 身份登录并映射到策略。 |
| `SSH_MCP_ALLOWED_CIPHERS` | 空 | 可选的 SSH 密码允许列表。 |
| `SSH_MCP_POLICY_FILE` | 未设置 | 包含部分策略覆盖的 JSON 文件。 |
| `SSH_MCP_POLICY_MODE` | `enforce` | 策略决策模式：`enforce` 或 `explain`。 |
| `SSH_MCP_ALLOW_RAW_SUDO` | `false` | 允许原始 `proc_sudo`；优先使用 `ensure_*` 工具。 |
| `SSH_MCP_ALLOW_DESTRUCTIVE_COMMANDS` | `false` | 允许匹配破坏性命令策略的命令。 |
| `SSH_MCP_ALLOW_DESTRUCTIVE_FS` | `false` | 允许破坏性文件系统操作，例如 `fs_rmrf`。 |
| `SSH_MCP_ALLOWED_HOSTS` | 空 | 策略和远程连接器安全检查的主机允许列表。 |
| `SSH_MCP_COMMAND_ALLOW` | 空 | 命令允许模式。 |
| `SSH_MCP_COMMAND_DENY` | 空 | 命令拒绝模式。 |
| `SSH_MCP_PATH_ALLOW_PREFIXES` | `/tmp,/var/tmp,/home,/Users` | 文件系统策略允许的远程路径前缀。 |
| `SSH_MCP_PATH_DENY_PREFIXES` | `/etc/sudoers,/etc/shadow,/etc/passwd,/boot,/dev,/proc` | 文件系统策略拒绝的远程路径前缀。 |
| `SSH_MCP_LOCAL_PATH_ALLOW_PREFIXES` | 操作系统临时目录 | 传输操作允许的本地路径。 |
| `SSH_MCP_LOCAL_PATH_DENY_PREFIXES` | 空 | 传输操作拒绝的本地路径。 |
| `SSH_MCP_TUNNEL_ALLOW_BIND_HOSTS` | `127.0.0.1,localhost,::1` | 隧道允许的本地绑定主机。 |
| `SSH_MCP_TUNNEL_DENY_BIND_HOSTS` | `0.0.0.0,::` | 隧道拒绝的本地绑定主机。 |
| `SSH_MCP_TUNNEL_ALLOW_REMOTE_HOSTS` | 空 | 可选的远程隧道目标主机允许列表。 |
| `SSH_MCP_TUNNEL_DENY_REMOTE_HOSTS` | 空 | 可选的远程隧道目标主机拒绝列表。 |
| `SSH_MCP_TUNNEL_ALLOW_PORTS` | 空 | 可选的隧道端口允许列表。 |
| `SSH_MCP_TUNNEL_DENY_PORTS` | 空 | 可选的隧道端口拒绝列表。 |
| `SSH_MCP_HTTP_HOST` | `127.0.0.1` | 可流式传输的 HTTP 绑定主机。 |
| `SSH_MCP_HTTP_PORT` | `3000` | 可流式传输的 HTTP 绑定端口。 |
| `SSH_MCP_HTTP_ALLOWED_ORIGINS` | `http://127.0.0.1,http://localhost` | HTTP 客户端允许的浏览器来源。 |
| `SSH_MCP_HTTP_BEARER_TOKEN_FILE` | 未设置 | HTTP 传输的持有者令牌文件。非环回持有者部署所需。 |
| `SSH_MCP_ENABLE_LEGACY_SSE` | `false` | 启用旧式 SSE 兼容性。 |
| `SSH_MCP_HTTP_MAX_REQUEST_BODY_BYTES` | `1048576` | 最大 HTTP 请求正文大小。 |
| `SSH_MCP_HTTP_MAX_SESSIONS` | `20` | 最大活动流式 HTTP MCP 会话数。过期会话首先被清理；如果容量仍然满，则逐出最旧的空闲会话，以免废弃的客户端导致持续的 502 错误。使用 `100` 进行 ChatGPT/Cloudflare 生产部署。 |
| `SSH_MCP_HTTP_SESSION_IDLE_TTL_MS` | `900000` | HTTP MCP 会话空闲超时，毫秒。使用 `300000` 进行 ChatGPT/Cloudflare 生产部署，客户端可能会在不删除的情况下放弃会话。 |
| `SSH_MCP_HTTP_PUBLIC_URL` | 未设置 | 受保护资源元数据的稳定公共 HTTPS MCP URL。 |
| `SSH_MCP_HTTP_TRUST_PROXY` | `false` | 信任反向代理转发头。 |
| `SSH_MCP_TOOL_PROFILE` | `full` | 活动的工具暴露配置文件。 |
| `SSH_MCP_CONNECTOR_PROFILE` | `full` | `SSH_MCP_TOOL_PROFILE` 的别名。 |
| `SSH_MCP_CONNECTOR_CREDENTIAL_PROVIDER` | `none` | 凭证提供者：`none`、`agent` 或 `command`。 |
| `SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND` | 未设置 | 当提供者为 `command` 时，外部凭证命令。 |
| `SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND_ARGS` | 空 | 传递给外部凭证命令的参数。 |
| `SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND_TIMEOUT_MS` | `5000` | 凭证命令超时，毫秒。 |
| `SSH_MCP_CONNECTOR_DEFAULT_USERNAME` | 未设置 | 连接器代理流的默认用户名。 |
| `SSH_MCP_HTTP_AUTH_MODE` | `bearer` | HTTP 认证模式：`bearer` 或 `oauth`。 |
| `SSH_MCP_OAUTH_ISSUER` | 未设置 | 预期 OAuth 发行者。 |
| `SSH_MCP_OAUTH_AUDIENCE` | 未设置 | 预期 OAuth 受众。 |
| `SSH_MCP_OAUTH_JWKS_URL` | 未设置 | OAuth JWKS URL。 |
| `SSH_MCP_OAUTH_RESOURCE` | 未设置 | OAuth 保护的资源标识符。 |
| `SSH_MCP_OAUTH_REQUIRED_SCOPES` | `ssh-mcp-pro.read` | 要求的 OAuth 范围。 |
| `SSH_MCP_OAUTH_ALLOWED_ALGORITHMS` | 未设置 | 可选的逗号分隔 JWT 算法允许列表，例如 `RS256,ES256`。当未设置时，使用内置的 OAuth 验证器默认值。 |
| `SSH_MCP_REMOTE_AGENT_MCP_PASSTHROUGH` | 未设置 | 启用后，带有 `1`、`true`、`yes` 或 `on`，让 `/mcp` 请求绕过远程控制平面，访问流式 HTTP MCP 处理程序。仅用于连接器路由迁移。 |
解析器还接受非 `SSH_MCP_*` 兼容别名 `PORT`、`KNOWN_HOSTS_PATH` 和 `STRICT_HOST_KEY_CHECKING`。
## 工具配置文件
`full` 暴露每个已注册的工具、资源和提示。所有其他配置文件都使用显式的每个配置文件允许集。`chatgpt` 和 `claude` 目前暴露与 `remote-safe` 相同的基线连接器工具，以及空的客户端特定扩展集，保留用于未来添加。
| 配置文件 | 暴露的工具 | 暴露的资源 | 暴露的提示 |
| --- | --- | --- | --- |
| `full` | 所有 SSH、进程、文件系统、传输、确保、隧道、连接器和系统工具。 | 所有运行时资源。 | 所有提示。 |
| `remote-safe` | `connector_status`、`ssh_hosts_list`、`ssh_policy_explain`、`ssh_host_inspect`、`ssh_mutation_plan`。 | `ssh-mcp-pro://capabilities/support-matrix`。 | `inspect-host-capabilities`、`plan-mutation`。 |
| `chatgpt` | 基线远程连接器工具加上空的 ChatGPT 扩展集。 | 与 `remote-safe` 相同的远程连接器子集。 | 与 `remote-safe` 相同的远程连接器子集。 |
| `claude` | 基线远程连接器工具加上空的 Claude 扩展集。 | 与 `remote-safe` 相同的远程连接器子集。 | 与 `remote-safe` 相同的远程连接器子集。 |
| `remote-readonly` | 与 `remote-safe` 相同的远程连接器子集。 | 与 `remote-safe` 相同的远程连接器子集。 | 与 `remote-safe` 相同的远程连接器子集。 |
| `remote-broker` | 与 `remote-safe` 相同的远程连接器子集。 | 与 `remote-safe` 相同的远程连接器子集。 | 与 `remote-safe` 相同的远程连接器子集。 |
## 安全默认值
ssh-mcp-pro 启动时具有严格的 SSH 主机密钥验证，拒绝 root 登录，拒绝原始 sudo，阻止破坏性命令和文件系统操作，除非策略允许。有关这些默认值的设计原理，请参阅 [SECURITY_DECISIONS.md](SECURITY_DECISIONS.md) 和漏洞报告 [SECURITY.md](SECURITY.md)。
## 更多文档
- [INSTALL.md](INSTALL.md) 涵盖完整的客户端设置和故障排除。
- [API 参考](https://oaslananka.github.io/ssh-mcp-pro/) 从已发布的 TypeScript 入口点生成。
- [CHANGELOG.md](CHANGELOG.md) 以 Keep a Changelog 格式记录发布历史。
- [AGENTS.md](AGENTS.md) 描述面向代理的操作指南。
- [examples/README.md](examples/README.md) 包含工作流程示例。
- [ARCHITECTURE.md](ARCHITECTURE.md) 解释主要的子系统和 ADRs。
- [REGISTRY_SUBMISSION.md](REGISTRY_SUBMISSION.md) 跟踪 MCP 注册表提交准备情况。
## 贡献
有关设置、质量门控、提交规则和拉取请求期望，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
ssh-mcp-pro 在 [MIT License](LICENSE) 下可用。
