mcp-ssh-tool

👁 npm version
👁 CI
👁 Security
👁 Official MCP Registry
👁 License: MIT
👁 npm downloads

面向运维人员、开发人员和 AI 客户端的生产级 MCP SSH 自动化工具。mcp-ssh-tool 可开启持久化 SSH 会话，并提供安全、结构化的工具，用于命令执行、文件操作、传输、隧道、软件包/服务管理、指标监控、资源访问及引导式提示。

v2 版本默认安全：开启严格的主机密钥验证，禁用 root 登录，原始 sudo 受策略限制，除非策略允许，否则拒绝破坏性命令和文件系统变更；远程 HTTP 仅在回环地址上启动，除非配置了 bearer 令牌和允许的来源。

为什么选择此服务器

• 信任： 中心化策略引擎、结构化审计事件、脱敏日志、严格的主机密钥以及机器可读的错误信息。

• MCP 质量： 本地客户端使用 stdio，远程客户端使用可流式传输的 HTTP，仅在显式兼容性标志下支持旧版 SSE。

• AI 友好工具： 稳定的输出模式、structuredContent、针对只读/破坏性/幂等行为的注解、资源以及精选提示词。

• 运维： 会话 TTL/驱逐、命令超时、传输校验和验证、真实的 SSH 转发、Prometheus 指标以及 OpenTelemetry 钩子。

• 可移植性： 优先使用 SFTP，针对基本文件操作提供 POSIX/BusyBox 感知 shell 后备方案，并明确支持边界。

快速开始

无需安装直接运行：

npx -y mcp-ssh-tool --version

或全局安装：

npm install -g mcp-ssh-tool

将 stdio MCP 服务器添加到您的客户端：

{
 "servers": {
 "ssh-mcp": {
 "type": "stdio",
 "command": "mcp-ssh-tool",
 "args": []
 }
 }
}

在您的 MCP 客户端中使用它：

Open a safe SSH session to prod-1 as deploy, inspect host capabilities, then show disk usage.

要求

• Node.js 22.22.2+ 或 24.14.1+ (仅限 LTS 版本)

• 对目标主机的 SSH 访问权限

• 包含已填充的 known_hosts 文件以进行严格的主机验证，或显式的每会话主机密钥策略

传输方式

除非同时配置了 --bearer-token-file 和允许的来源，否则拒绝非回环地址的 HTTP 启动。

安全默认设置

每会话的 policyMode: "explain" 会返回计划/判定而不执行。当 AI 客户端需要总结风险时，请在变更前使用此模式。

策略示例

设置 SSH_MCP_POLICY_FILE=/etc/mcp-ssh-tool/policy.json：

{
 "mode": "enforce",
 "allowRootLogin": false,
 "allowRawSudo": false,
 "allowDestructiveCommands": false,
 "allowDestructiveFs": false,
 "allowedHosts": ["^prod-[0-9]+\\.example\\.com$"],
 "commandAllow": ["^(uname|df|uptime|systemctl status)\\b"],
 "commandDeny": ["rm\\s+-rf\\s+/", "shutdown", "reboot"],
 "pathAllowPrefixes": ["/tmp", "/var/tmp", "/home/deploy"],
 "pathDenyPrefixes": ["/etc/shadow", "/etc/sudoers", "/boot", "/dev", "/proc"]
}

简单的部署可以使用环境变量覆盖，例如 SSH_MCP_ALLOW_RAW_SUDO=true、SSH_MCP_ALLOWED_HOSTS=prod-1.example.com 或 SSH_MCP_PATH_ALLOW_PREFIXES=/tmp,/home/deploy。

核心工具

• ssh_open_session, ssh_close_session, ssh_list_sessions, ssh_ping, ssh_list_configured_hosts, ssh_resolve_host

• proc_exec, proc_sudo, proc_exec_stream

• fs_read, fs_write, fs_list, fs_stat, fs_mkdirp, fs_rmrf, fs_rename

• file_upload, file_download

• ensure_package, ensure_service, ensure_lines_in_file, patch_apply

• os_detect, get_metrics

• tunnel_local_forward, tunnel_remote_forward, tunnel_list, tunnel_close

所有工具均返回文本及稳定的 structuredContent。工具元数据包含标题、输出模式以及披露只读、破坏性、幂等和外部副作用行为的注解。

资源与提示词

资源：

• mcp-ssh-tool://sessions/active

• mcp-ssh-tool://metrics/json

• mcp-ssh-tool://metrics/prometheus

• mcp-ssh-tool://ssh-config/hosts

• mcp-ssh-tool://policy/effective

• mcp-ssh-tool://audit/recent

• mcp-ssh-tool://capabilities/support-matrix

提示词：

• safe-connect

• inspect-host-capabilities

• plan-mutation

• managed-config-change

支持矩阵

客户端示例

ChatGPT 或 Claude Desktop：

{
 "mcpServers": {
 "ssh-mcp": {
 "command": "npx",
 "args": ["-y", "mcp-ssh-tool"]
 }
 }
}

VS Code 或 Cursor：

{
 "servers": {
 "ssh-mcp": {
 "type": "stdio",
 "command": "mcp-ssh-tool"
 }
 }
}

通过 HTTP 使用 MCP Inspector：

printf '%s' 'super-secret-token' > .mcp-token
mcp-ssh-tool --transport=http --host 127.0.0.1 --port 3000 --bearer-token-file .mcp-token

配置

高价值环境变量：

已弃用的别名 STRICT_HOST_KEY_CHECKING 和 SSH_MCP_STRICT_HOST_KEY 在 v2 兼容周期内仍被接受。建议优先使用 SSH_MCP_HOST_KEY_POLICY。

开发

使用 .nvmrc / .node-version 中的精确本地运行时，然后运行：

npm ci
npm run check

实时 SSH 套件为可选：

RUN_SSH_INTEGRATION=1 npm run test:integration
RUN_SSH_E2E=1 npm run test:e2e

本地质量门禁是分层的：

• pre-commit：格式化暂存文件并仅对暂存的 TypeScript 进行 lint 检查

• pre-push：运行 npm run check:push

• task hooks：在安装 pre-commit 时运行跟踪的 npm 钩子及 .pre-commit-config.yaml 钩子

• 手动/完全对齐：task ci 或 npm run check

CI/CD 所有权

个人仓库 https://github.com/oaslananka/mcp-ssh-tool 是规范的源仓库。自动 CI/CD、供应链安全检查、受信任的 npm 发布以及 MCP Registry 发布仅从 https://github.com/oaslananka-lab/mcp-ssh-tool 运行。组织仓库从规范源拉取；个人仓库的推送和发布工作流已禁用。

npm 包的 repository.url 特意指向组织仓库，以便 npm 来源验证可以确认发布的工件来自构建它的同一个 GitHub Actions 仓库。

参见 docs/ci-cd-topology.md 获取组织同步、发布流程和手动后备指南。

文档

• ARCHITECTURE.md

• SECURITY_DECISIONS.md

• MIGRATION.md

• docs/ci-cd-topology.md

• docs/development.md

• docs/release.md

• docs/doppler.md

• docs/operations.md

• docs/branch-protection.md

• docs/maintenance-policy.md

• docs/api-stability.md

• docs/threat-model.md

• docs/configuration.md

• docs/security-model.md

• docs/troubleshooting.md

• docs/enterprise-deployment.md

许可证

MIT 许可证。参见 LICENSE。

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• connector_statusA
• ensure_lines_in_fileA
• ensure_packageC
• ensure_serviceB
• file_downloadA
• file_uploadB
• fs_listC
• fs_mkdirpA