SSH Client MCP Server

SSH 客户端 MCP 服务

SSH Client MCP Server 是一个本地 Model Context Protocol (MCP) 服务，可让大模型和其他 MCP 客户端通过 SSH 在远程主机上执行 Shell 命令。它可在 Linux、macOS 或 Windows 上运行，并适用于任何可连接的 SSH 服务端（Linux、macOS、装有 OpenSSH 的 Windows 等）。

基于 somamcp 构建——这是一个基于 FastMCP 的实用 MCP 框架，支持遥测、内省和后端抽象。

目录

• 快速开始
• 功能
• 工具
• 安装
• 配置
• 客户端设置
• 测试
• 开发
• 免责声明

Monorepo

此仓库是一个包含三个软件包的 pnpm monorepo：

软件包	npm 名称	作用
packages/core	@ssh-mcp/core（私有）	共享 SSH 连接池、tmux 命令构造器和身份验证解析。打包到其他软件包中；不单独发布。
packages/connector	ssh-client-mcp-server	单主机 MCP 服务（原始软件包）。面向一个已配置 SSH 主机的 exec + tmux_* 工具。
packages/orchestrator	ssh-fleet-mcp-server	多主机集群 MCP 服务。由 TOML 集群配置驱动、按主机路由的 exec + tmux_* 工具。

运行所有软件包的完整验证套件：

pnpm -r validate

快速开始

1. 配置 MCP 客户端（Claude Desktop、Cursor、Cline 等），通过 npx 启动此服务——参见客户端设置。
2. 请大模型在目标主机上运行 Shell 命令。

无需全局安装——npx 会获取并运行最新发布版本。

功能

• 单个 exec 工具——在远程主机上运行 Shell 命令并返回 stdout。stderr 会作为结构化错误显示。
• 四种身份验证模式——密码、密钥文件、来自环境变量的密钥（例如由 envpkt、Vault、Doppler 注入），或 SSH_AUTH_SOCK（系统 ssh-agent、1Password、Bitwarden Desktop、KeePassXC）。
• 智能路径展开——--key 支持通过 functype-os 处理 ~、$VAR、${VAR} 和相对路径。未解析的变量会立即触发带类型的错误。
• 操作系统用户回退——省略 --user 时，默认使用当前操作系统用户名。
• 身份验证快速失败——SSH 密钥会在服务启动时加载并验证，而不是等到首次调用 exec 时才处理。
• 开箱即用的内省功能——由 somamcp 自动注册 soma_health、soma_capabilities、soma_connections。
• 跨平台——可在 Linux、macOS、Windows 上运行（任何支持 Node 22+ 的环境）。

工具

工具	描述
exec	在远程 SSH 服务端执行 Shell 命令并返回 stdout。
soma_health	服务运行时间、状态和活动会话数。
soma_capabilities	列出已注册的工具、资源和提示词。
soma_connections	网关连接状态（此处未使用）。

持久会话（tmux）

要跨调用驱动长期运行的交互式进程（例如远程编码 Agent），服务会提供由 tmux 支持的工具。远程主机必须安装 tmux。

• tmux_list — 列出正在运行的 tmux 会话。
• tmux_send({ session?, input, submit? }) — 将 input 输入到 session（如果不存在则创建）；除非设置 submit: false，否则按 Enter。
• tmux_read({ session?, lines? }) — 返回最近的窗格记录（lines 默认为 200，最大为 2000）。
• tmux_keys({ session?, keys }) — 发送控制键或特殊键，例如 { keys: ["C-c"] }。

session 默认为 --tmux-session（默认值为 agent）。提示：以按行处理的模式（而非全屏 TUI）运行 Agent，这样 tmux_read 返回的记录会更整洁。

安装

通过 npx 运行（推荐）

无需安装步骤——MCP 客户端会按需启动它。请参阅客户端设置。

全局安装

npm install -g ssh-client-mcp-server
# then:
ssh-client-mcp-server --host=1.2.3.4 --user=root --password=pass

从源代码安装（适用于贡献者）

git clone https://github.com/jordanburke/ssh-client-mcp-server.git
cd ssh-client-mcp-server
pnpm install
pnpm build

配置

服务从 CLI 标志读取 SSH 连接信息：

标志	必填	默认值	描述
--host	是	—	远程 SSH 服务的主机名或 IP 地址。
--user	否	OS 用户名	SSH 用户名。若未指定，则回退到本地 OS 用户（whoami）。
--port	否	22	SSH 端口。
--password	否*	—	SSH 密码。
--key	否*	—	SSH 私钥的路径。支持 ~、$VAR、${VAR} 和相对路径。
--key-env	否*	—	存有私钥 PEM 的环境变量名称（例如由 envpkt、Vault、Doppler 注入）。
--agent	否*	—	设置为 true 以使用 SSH_AUTH_SOCK（系统 ssh-agent、1Password、Bitwarden Desktop、KeePassXC）。

*身份验证优先级为 --password → --key → --key-env → --agent。如果均未设置，服务仍会启动，但 ssh2 会在首次 exec 时身份验证失败。

从密码管理器获取密钥（Bitwarden / 1Password / KeePassXC）

这些工具都可以通过 SSH_AUTH_SOCK 提供 SSH 密钥。解锁保险库，确认 Agent 已启用，然后使用 --agent=true 运行——服务不会接触私钥。

# verify the agent is reachable
ssh-add -l

# launch the MCP server through it
ssh-client-mcp-server --host=1.2.3.4 --user=root --agent=true

对于 Bitwarden Desktop ≥ 2024.12：启用 设置 → SSH agent，然后在 macOS 上确认 launchctl getenv SSH_AUTH_SOCK 指向 Bitwarden 的套接字。

从 envpkt 获取密钥（或使用任何注入环境变量的工具）

将 PEM 作为密封值存储在 envpkt.toml 中，然后通过 envpkt exec 启动：

envpkt exec -- ssh-client-mcp-server --host=1.2.3.4 --user=root --key-env=MY_SSH_KEY

同样的方法也适用于 HashiCorp Vault、Doppler、Infisical、AWS Secrets Manager，或任何将密钥写入 process.env 的包装工具。

客户端设置

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "ssh-client-mcp-server": {
      "command": "npx",
      "args": ["-y", "ssh-client-mcp-server", "--host=1.2.3.4", "--user=root", "--key=~/.ssh/id_ed25519"]
    }
  }
}

密码身份验证

将 --key 参数替换为 --password=hunter2。避免将此内容提交到版本控制中。

使用当前 OS 用户

完全省略 --user——服务默认使用你的本地用户名。

其他 MCP 客户端

任何支持 stdio MCP 传输的客户端都可以使用。command / args 的格式相同。

测试

使用已发布的构建版本

npx @modelcontextprotocol/inspector npx ssh-client-mcp-server --host=1.2.3.4 --user=root --key=~/.ssh/id_ed25519

使用本地构建版本（运行 pnpm build 后）

pnpm inspect

这会构建并启动 MCP Inspector，并将其指向 dist/index.js。

开发

所有工具都委托给 ts-builds：

pnpm validate      # format → lint → typecheck → test → build
pnpm test          # vitest run
pnpm test:watch    # vitest watch mode
pnpm build         # production build to dist/
pnpm dev           # tsdown watch mode to lib/
pnpm inspect       # build + launch MCP Inspector

纯辅助函数（parseArgv、validateConfig、resolveAuth、effectiveUser）位于 src/config.ts 中，并由 test/config.spec.ts 覆盖（18 个用例，包括基于临时文件的密钥读取和环境变量展开）。

免责声明

根据 MIT License 提供。使用风险自负。与任何 SSH 供应商或 MCP 提供方均无关联，也未获得其认可。授予大模型 shell 访问权限时请务必谨慎——审查命令、限制目标账户的权限，并考虑使用跳板机。

贡献

欢迎在 jordanburke/ssh-client-mcp-server 提交问题和 PR。提交前请运行 pnpm validate。