AI导哈

SSH客户端MCP服务器

一个本地模型上下文协议（MCP）服务器，允许LLM和其他MCP客户端通过SSH在远程主机上执行shell命令。

  • by jordanburke
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 jordanburke/ssh-client-mcp-server

使用说明

SSH客户端MCP服务器

SSH客户端MCP服务器 是一个本地模型上下文协议（MCP）服务器，允许LLM和其他MCP客户端通过SSH在远程主机上执行shell命令。它从Linux、macOS或Windows运行，并针对任何可访问的SSH服务器（Linux、macOS、带OpenSSH的Windows等）。

建立在 somamcp --基于FastMCP的功能性MCP框架，具有遥测、自检和后端抽象功能。

目录

单体仓库

这个仓库是一个pnpm单仓库，有三个包：

包 npm名称 角色
packages/core @ssh-mcp/core （私有） 共享SSH池、tmux命令构建器和身份验证解析。捆绑在其他包裹中；未单独发表。
packages/connector ssh-client-mcp-server 单主机MCP服务器（原包装）。 exec + tmux_* 一个配置的SSH主机的工具。
packages/orchestrator ssh-fleet-mcp-server 多主机机群MCP服务器。主机已路由 exec + tmux_* 由TOML舰队配置驱动的工具。

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

pnpm -r validate

快速开始

  1. 配置您的MCP客户端（Claude Desktop、Cursor、Cline等）以通过以下方式启动此服务器 npx --看 客户端设置.
  2. 让LLM在目标主机上运行shell命令。

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

特性

  • 单身的 exec 工具 --在远程主机上运行shell命令，返回stdout。stderr显示为结构化错误。
  • 四种身份验证模式 --密码、密钥文件、来自环境变量的密钥（例如通过注入 ENVPKT、保险库、多普勒），或 SSH_AUTH_SOCK （系统ssh代理、1Password、Bitwarden桌面、KeePassXC）。
  • 智能路径扩展 — --key 支持 ~, $VAR, ${VAR}，以及通过以下路径的相对路径 functype-os未解析的变量会因类型错误而快速失败。
  • 操作系统用户回退 — --user 省略时默认为当前操作系统用户名。
  • 快速身份验证失败 --SSH密钥是在服务器启动时加载和验证的，而不是在第一次启动时 exec 电话。
  • 开箱即用的内省 — soma_health, soma_capabilities, soma_connections 由somacp自动注册。
  • 跨平台 --在Linux、macOS、Windows（Node 22+运行的任何地方）上运行。

工具

工具 说明
exec 在远程SSH服务器上执行shell命令并返回stdout。
soma_health 服务器正常运行时间、状态、活动会话计数。
soma_capabilities 枚举已注册的工具、资源和提示。
soma_connections 网关连接状态（此处未使用）。

持续会话（tmux）

为了跨调用驱动长时间运行的交互式进程（例如远程编码代理），服务器公开了tmux支持的工具。tmux必须安装在远程主机上。

  • tmux_list --列出实时tmux会话。
  • tmux_send({ session?, input, submit? }) --类型 input 进入 session （若缺失则创建）；按下Enter键，除非 submit: false.
  • tmux_read({ session?, lines? }) --返回最近的窗格记录(lines 默认值200，最大值2000）。
  • tmux_keys({ session?, keys }) --发送控制/特殊密钥，例如。 { keys: ["C-c"] }.

session 默认为 --tmux-session （默认值 agent).提示：以面向线路的模式（而不是全屏TUI）运行代理，因此 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 yes -- 远程SSH服务器的主机名或IP。
--user no 操作系统用户名 SSH用户名。回退到本地操作系统用户(whoami)当省略时。
--port 没有 22 SSH端口
--password 没有* -- SSH密码。
--key no* -- 私有SSH密钥的路径。支持 ~, $VAR, ${VAR}以及相对路径。
--key-env no* -- 持有私钥PEM的环境变量的名称（例如由envpkt、Vault、Doppler注入）。
--agent 否* -- 设置为 true 使用 SSH_AUTH_SOCK （系统ssh代理、1Password、Bitwarden桌面、KeePassXC）。

*身份验证优先级为 --password → --key → --key-env → --agent。如果没有设置，服务器将启动，但ssh2将无法首先进行身份验证 exec.

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

每个都可以通过以下方式公开您的SSH密钥 SSH_AUTH_SOCK。解锁保管库，确认已启用代理，然后使用运行 --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桌面≥2024.12：启用 设置→ SSH代理，然后在macOS上确认 launchctl getenv SSH_AUTH_SOCK 指向Bitwarden的插座。

从envpkt（或任何注入env变量的工具）中提取密钥

将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_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 arg与 --password=hunter2。避免将此检查到版本控制中。

使用当前操作系统用户

省略 --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检查员 指向 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种情况，包括tempfile支持的密钥读取和env-var扩展）。

免责声明

根据 MIT许可证.使用风险自负。不隶属于任何SSH供应商或MCP提供商，也不受其认可。请谨慎授予LLMs shell访问权限——审核命令，限制目标帐户权限，并考虑使用跳转框。

贡献

欢迎在 jordanburke/ssh客户端mcp服务器请快跑 pnpm validate 在提交之前。

相关 MCP