Ssh Mcp Pro

ssh-mcp-pro

ssh-mcp-pro 是一个用于 SSH 自动化的安全模型上下文协议（MCP）服务。它让支持 MCP 的客户端能够通过受策略控制的工具打开 SSH 会话、检查主机、运行受保护的命令、管理文件、传输制品、创建隧道，以及执行幂等的软件包或服务操作。

前置条件

• Node.js >=22.22.2 或 >=24.15.0 或 >=26.3.0
• pnpm >=11.0.9
• 目标主机的 SSH 访问权限
• Docker，仅用于本地集成测试和容器映像构建

安装

使用 pnpm 全局安装：

pnpm add --global ssh-mcp-pro
ssh-mcp-pro --version

无需全局安装即可运行：

npx ssh-mcp-pro

仅使用 pnpm 的环境请使用：

pnpm dlx ssh-mcp-pro

发布版本标签对应的容器映像托管在 GitHub Container Registry：

docker run --rm ghcr.io/oaslananka/ssh-mcp-pro:1.0.0 --version

映像适用于 linux/amd64 和 linux/arm64，并带有精确的 semver 和 Git 标签别名。生产部署应优先使用发布工作流记录的、固定到摘要的 引用。有关标签策略、固定到摘要的示例和注册表验证步骤，请参阅 Docker 使用说明。

快速入门

通用 stdio MCP 配置：

{
  "name": "ssh-mcp-pro",
  "command": "ssh-mcp-pro",
  "type": "stdio"
}

VS Code 设置样式：

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

Claude Desktop 样式：

{
  "mcpServers": {
    "ssh-mcp-pro": {
      "command": "ssh-mcp-pro",
      "args": []
    }
  }
}

注册后，请先使用严格的主机密钥策略进行发现：

List configured SSH hosts, open a session to bastion.example.com as deploy with hostKeyPolicy=strict, then run os_detect.

使用方法

通过 stdio 从 MCP 客户端使用 ssh-mcp-pro，或运行 HTTP 传输以使用适合远程环境的连接器配置文件。请从只读发现工具开始，检查当前策略，并在运行远程命令前创建明确的会话：

List configured SSH hosts, explain the active SSH policy, connect to the selected host, then report its operating system and disk usage.

其他工作流请参阅 examples/README.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	未设置	用于在严格与不安全主机密钥检查之间切换的旧版布尔别名。
SSH_MCP_HOST_KEY_POLICY	strict	主机密钥模式：strict、accept-new 或 insecure。
SSH_MCP_KNOWN_HOSTS_PATH	~/.ssh/known_hosts	用于严格主机密钥验证的已知主机文件。
SSH_MCP_ALLOW_ROOT_LOGIN	false	允许以 root 身份登录 SSH，并同步到策略中。
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	OS 临时目录	传输操作允许使用的本地路径。
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	Streamable HTTP 绑定主机。
SSH_MCP_HTTP_PORT	3000	Streamable HTTP 绑定端口。
SSH_MCP_HTTP_ALLOWED_ORIGINS	http://127.0.0.1,http://localhost	HTTP 客户端允许的浏览器来源。
SSH_MCP_HTTP_BEARER_TOKEN_FILE	未设置	HTTP 传输使用的 Bearer 令牌文件。非环回 Bearer 部署必须设置。
SSH_MCP_ENABLE_LEGACY_SSE	false	启用旧版 SSE 兼容性。
SSH_MCP_HTTP_MAX_REQUEST_BODY_BYTES	1048576	HTTP 请求正文的最大大小。
SSH_MCP_HTTP_MAX_SESSIONS	20	活跃 Streamable HTTP MCP 会话的最大数量。会先清理过期会话；如果容量仍已满，则逐出最久未活动的会话，避免客户端弃用会话导致持续出现 502 错误。ChatGPT/Cloudflare 生产部署请使用 100。
SSH_MCP_HTTP_SESSION_IDLE_TTL_MS	900000	HTTP MCP 会话空闲超时时间，单位为毫秒。对于客户端可能不发送 DELETE 而弃用会话的 ChatGPT/Cloudflare 生产部署，请使用 300000。
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 请求绕过远程控制平面，直接到达 Streamable 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_CHATGPT_EXTRA_TOOLS 和 SSH_MCP_CLAUDE_EXTRA_TOOLS 可在仅限环回的开发环境中扩展其配置。非环回 HTTP 启动时，会根据规范的远程安全允许列表验证完整解析后的工具集，并拒绝未知工具、会话工具、传输工具、文件系统修改工具、进程工具、sudo 工具、服务修改工具或隧道工具。启动错误仅列出被拒绝的工具名称。在本地添加扩展，并不意味着该工具获准公开给公共连接器使用。

安全默认设置

ssh-mcp-pro 默认严格验证 SSH 主机密钥、拒绝 root 登录、拒绝直接使用 sudo，并在策略未允许时阻止破坏性命令和文件系统操作。此外，除非已配置身份验证、来源、公共 HTTPS URL、严格的主机密钥验证、远程安全工具配置和主机允许列表，否则它会拒绝非环回 HTTP 启动。有关漏洞报告，请参阅 SECURITY.md；有关这些默认设置背后的设计理由，请参阅 SECURITY_DECISIONS.md。

更多文档

• INSTALL.md 涵盖完整的客户端设置和故障排查。
• API 参考 根据已发布的 TypeScript 入口点生成。
• CHANGELOG.md 以 Keep a Changelog 格式记录发布历史。
• AGENTS.md 介绍面向 Agent 的操作指南。
• examples/README.md 包含工作流示例。
• ARCHITECTURE.md 说明主要子系统和 ADR。
• REGISTRY_SUBMISSION.md 跟踪 MCP Registry 的提交准备情况。
• docs/tutorials/getting-started.md、 docs/how-to/、docs/reference/ 和 docs/explanation/ 按任务类型（教程、操作指南、参考、说明）整理上述文档。
• docs/troubleshooting.md 介绍常见故障。

项目健康状况与治理

• GOVERNANCE.md 介绍当前的决策方式。
• MAINTAINERS.md 列出当前维护者。
• ROADMAP.md 跟踪已知的流程缺口，以及计划如何弥补这些缺口。
• CODE_OF_CONDUCT.md 规定社区行为准则。
• docs/repo-maturity-report.md 是一份以证据为依据的审查报告，评估此仓库的开源和 OpenSSF 成熟度，并说明哪些方面尚未到位。

参与贡献

有关环境搭建、质量门槛、提交规则和拉取请求要求，请参阅 CONTRIBUTING.md。参与者须遵守行为准则。

许可证

ssh-mcp-pro 采用 MIT 许可证。

Agent 插件和运行时配置

此仓库负责维护 ssh-mcp-pro 的产品级 Agent 插件、MCP 运行时配置和产品专属技能。中央 agent-tools 仓库应收录此插件，但清单和工作流说明保存在此处，以便与实际的 MCP 服务包保持同步。

文件	用途
.claude-plugin/plugin.json	符合 Claude Code 要求的产品插件清单。
.mcp.json	Claude Code 项目本地 MCP 服务配置。
.codex/config.example.toml	Codex CLI MCP 配置示例。
.vscode/mcp.example.json	VS Code / GitHub Copilot 工作区 MCP 配置示例。
opencode.example.jsonc	OpenCode 项目 MCP 配置示例。
.opencode/skills/	OpenCode 原生镜像技能定义。
docs/agent-runtime-config.md	Agent 运行时设置和验证说明。

在本地验证插件打包：

claude plugin validate .