内容
# SSH MCP 服务器
[](https://www.npmjs.com/package/@xiaoyankonling/ssh-mcp)
[](https://www.npmjs.com/package/@xiaoyankonling/ssh-mcp)
[](https://nodejs.org/)
[](./LICENSE)
[](https://github.com/KonglingDaDa/ssh-mcp/stargazers)
[](https://github.com/KonglingDaDa/ssh-mcp/forks)
[](https://github.com/KonglingDaDa/ssh-mcp/actions)
[](https://github.com/KonglingDaDa/ssh-mcp/issues)
[](https://archestra.ai/mcp-catalog/KonglingDaDa__ssh-mcp)
**SSH MCP 服务器** 是一个本地模型上下文协议（MCP）服务器，提供 SSH 控制，用于 Linux 和 Windows 系统，使 LLMs 和其他 MCP 客户端能够通过 SSH 安全地执行 shell 命令。
## 目录
- [快速入门](#快速入门)
- [功能](#功能)
- [安装](#安装)
- [客户端设置](#客户端设置)
- [AI 使用技能](#AI-使用技能)
- [测试](#测试)
- [免责声明](#免责声明)
- [支持](#支持)
## 快速入门
- [安装](#安装) SSH MCP 服务器
- [配置](#配置) SSH MCP 服务器
- [设置](#客户端设置) 您的 MCP 客户端（例如 Claude Desktop、Cursor 等）
- 通过自然语言在 Linux 或 Windows 服务器上执行远程 shell 命令
## 功能
- 符合 MCP 的服务器，暴露 SSH 功能
- 在远程 Linux 和 Windows 系统上执行 shell 命令
- 通过密码或 SSH 密钥进行安全身份验证
- 通过 YAML/JSON 文件进行本地配置文件管理
- 运行时配置文件管理工具（`profiles-list/find/use/reload/note-update/profiles-test`）
- 操作上下文的配置文件备注/标签
- 使用 TypeScript 和官方 MCP SDK 构建
- **可配置的超时保护**，带有 SSH 通道终止和连接清理
- **超时处理** - 请求远程命令终止（如果支持），然后关闭通道和连接
### 工具
- `exec`：在远程服务器上执行 shell 命令
- **参数：**
- `command`（必填）：要在远程 SSH 服务器上执行的 shell 命令
- `description`（可选）：命令执行的客户端描述，不会追加到可执行命令中
- `timeoutMs`（可选）：每个命令的超时毫秒数
- **超时配置：**
- `sudo-exec`：使用 sudo 提升权限执行 shell 命令
- **参数：**
- `command`（必填）：要使用 sudo 以 root 用户身份执行的 shell 命令
- `description`（可选）：命令执行的客户端描述，不会追加到可执行命令中
- `timeoutMs`（可选）：每个命令的超时毫秒数
- **备注：**
- 需要在活动配置文件中设置 `sudoPassword` 以进行密码保护的 sudo
- 可以使用 `--disableSudo` 或启动配置默认值禁用，如果不需要或无法使用 sudo 访问权限
- 当配置文件中设置了 `suPassword` 时，`exec` 命令会通过 `su -c` 而不是保持共享 root shell 打开来运行每个命令
- 如果服务器启动时带有 `--disableSudo`，则该工具将不可用
- **超时配置：**
- 超时通过命令行参数 `--timeout` 配置（毫秒）
- 默认超时：60000ms（1 分钟）
- 当命令超时时，服务器发送 `TERM`（如果支持），关闭 SSH 通道并断开连接；远程子进程清理取决于 SSH 服务器和命令行为
- **最大命令长度配置：**
- 最大命令字符通过 `--maxChars` 配置
- 默认值：`1000`
- 无限制模式：设置 `--maxChars=none` 或任何 `<= 0` 值（例如 `--maxChars=0`）
- `profiles-list`：列出配置文件摘要（`id/name/host/port/note/tags/active`），屏蔽敏感字段
- `profiles-find`：通过 `id/name/host/user/note/tags` 查找配置文件候选
- `profiles-test`：测试 TCP 连接性、SSH 握手和配置文件身份验证
- `profiles-use`：在运行时切换活动配置文件，持久化 `activeProfile`，并在下一个命令上重新创建 SSH 连接
- `profiles-reload`：从磁盘重新加载配置文件，并从启动覆盖或文件 `activeProfile` 解析活动配置文件
- `profiles-create`：在运行时动态创建配置文件模板（备注可选但推荐）
- `profiles-note-update`：更新和持久化简洁的配置文件备注
- `profiles-delete-prepare`：准备破坏性删除（创建备份并返回确认有效载荷）
- `profiles-delete-confirm`：使用确切的 `deleteRequestId + confirmationText` 完成删除
## 安装
1. **克隆仓库：**
```bash
git clone https://github.com/KonglingDaDa/ssh-mcp.git
cd ssh-mcp
```
2. **安装依赖：**
```bash
npm install
```
## 客户端设置
您可以配置您的 IDE 或 LLM，如 Cursor、Windsurf、Claude Desktop，以使用此 MCP 服务器。
### 配置文件模式
此服务器现在仅以配置文件模式运行。
使用 `--config` 加载本地 YAML/JSON 文件中的多个 SSH 配置文件。
**参数：**
- `config`：配置文件路径（`.yaml`、`.yml`、`.json`)
- `profile`：启动时活动配置文件的可选覆盖
- `timeout`：可选的命令超时毫秒数覆盖
- `maxChars`：可选的命令长度覆盖
- `disableSudo`：禁用 `sudo-exec` 的可选标志
**重要：**
- 旧版启动参数（`--host`、`--user`、`--password`、`--key` 等）不再受支持。
- 动态目标管理通过配置文件工具（`profiles-list/find/use/create/delete-*`）完成。
示例：
```bash
npx -y @xiaoyankonling/ssh-mcp -- --config=./examples/ssh-mcp.profiles.yaml --profile=jp-relay
```
### 配置文件格式
完整示例位于 `examples/ssh-mcp.profiles.yaml`。
```yaml
version: 1
activeProfile: fi-template
defaults:
timeout: 120000
maxChars: none
disableSudo: false
profiles:
- id: fi-template
name: 芬兰模板机
host: fi-template.example.com
port: 9900
user: root
auth:
type: password
password: "${SSH_TEMPLATE_PASSWORD}"
sudoPassword: "${SSH_TEMPLATE_SUDO_PASSWORD}"
note: "模板维护机，做 cloud-init 和预装验证"
tags: [template, fi]
```
备注：
- `${ENV_VAR}` 占位符在加载时扩展
- `profiles[].id` 和 `activeProfile` 必须是稳定的 ASCII 字符：字母、数字、`.`、`_` 或 `-`，以字母或数字开头；使用 `name` 作为人类可读的标签，如中文服务器名称
- `auth.type=password` 需要 `auth.password`
- `auth.type=key` 需要 `auth.keyPath` 且文件必须存在
- `activeProfile` 必须与 `profiles[].id` 之一匹配
- `profiles-reload` 重新读取文件并使用文件的 `activeProfile`，除非启动 `--profile` 覆盖仍然有效
- `disableSudo` 更改 MCP 工具界面，因此在启动时解析；更改配置文件后重启 MCP 服务器
### 动态模板管理工作流
1. 在运行时创建模板：
- 调用 `profiles-create`
- 默认情况下，创建的配置文件立即激活
2. 保持备注简洁：
- 如果省略 `note`，工具可以从 `contextSummary` 派生简洁的备注
3. 快速验证目标：
- 调用 `profiles-test` 在执行命令之前验证 TCP/SSH/身份验证
4. 安全删除（两步）：
- 首先调用 `profiles-delete-prepare`
- 审查返回的配置文件 + 备份路径 + 确认文本与用户
- 然后调用 `profiles-delete-confirm`
`profiles-delete-confirm` 需要以下格式的确切确认文本：
```text
DELETE <profileId>
```
这防止了意外删除配置文件并确保在删除之前存在备份。
### Claude 代码
您可以使用 `claude mcp add` 命令将此 MCP 服务器添加到 Claude Code 中。这是 Claude Code 的推荐方法。
**基本安装：**
```bash
claude mcp add --transport stdio ssh-mcp -- npx -y @xiaoyankonling/ssh-mcp -- --config=/path/to/ssh-mcp.profiles.yaml
```
**安装示例：**
**使用配置文件：**
```bash
claude mcp add --transport stdio ssh-mcp -- npx -y @xiaoyankonling/ssh-mcp -- --config=./examples/ssh-mcp.profiles.yaml
```
**使用启动配置文件覆盖：**
```bash
claude mcp add --transport stdio ssh-mcp -- npx -y @xiaoyankonling/ssh-mcp -- --config=./examples/ssh-mcp.profiles.yaml --profile=jp-relay
```
**使用自定义超时和无字符限制：**
```bash
claude mcp add --transport stdio ssh-mcp -- npx -y @xiaoyankonling/ssh-mcp -- --config=./examples/ssh-mcp.profiles.yaml --timeout=120000 --maxChars=none
```
**禁用 Sudo 工具：**
```bash
claude mcp add --transport stdio ssh-mcp -- npx -y @xiaoyankonling/ssh-mcp -- --config=./examples/ssh-mcp.profiles.yaml --disableSudo
```
**安装范围：
您可以指定添加服务器时的范围：
- **本地范围**（默认）：用于当前项目中的个人使用
```bash
claude mcp add --transport stdio ssh-mcp --scope local -- npx -y @xiaoyankonling/ssh-mcp -- --config=/path/to/ssh-mcp.profiles.yaml
```
- **项目范围**：通过 `.mcp.json` 文件与团队共享
```bash
claude mcp add --transport stdio ssh-mcp --scope project -- npx -y @xiaoyankonling/ssh-mcp -- --config=./config/ssh-mcp.profiles.yaml
```
- **用户范围**：在所有项目中可用
```bash
claude mcp add --transport stdio ssh-mcp --scope user -- npx -y @xiaoyankonling/ssh-mcp -- --config=/absolute/path/to/ssh-mcp.profiles.yaml
```
**验证安装：
添加服务器后，重启 Claude Code 并询问 Cascade 执行命令：
```
"你能运行 'ls -la' 在远程服务器上吗？"
```
有关 Claude Code 中 MCP 的更多信息，请参阅 [官方文档](https://docs.claude.com/en/docs/claude-code/mcp)。
## AI 使用技能
此仓库在 `skills/ssh-mcp-operator/` 包含一个 Codex 技能，用于教授 AI 代理如何在本地部署后使用此 MCP 服务器。
克隆仓库后，将 `skills/ssh-mcp-operator/` 复制或符号链接到您的 Codex 技能目录，然后调用它为：
```text
$ssh-mcp-operator
```
该技能教导代理：
- 使用 `profiles-list` 发现当前配置文件路径和活动配置文件
- 使用 `profiles-find` 按 `id/name/host/note/tags` 查找目标
- 使用 `profiles-use` 切换目标
- 使用 `profiles-reload` 热加载 `ssh-mcp.profiles.yaml` 更改
- 在重要命令之前使用 `profiles-test` 测试目标
- 安全使用 `exec` 和 `sudo-exec`，包括超时和破坏性命令确认
- 保持配置文件 `id` 值作为 ASCII 字符，同时允许中文显示名称
## 测试
您可以使用 [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) 进行此 MCP 服务器的视觉调试。
```sh
npm run inspect
```
## 免责声明
SSH MCP 服务器根据 [MIT License](./LICENSE) 提供。使用风险自负。本项目与任何 SSH 或 MCP 提供商无关，也未得到他们的认可。
## 贡献
我们欢迎贡献！请参阅我们的 [贡献指南](./CONTRIBUTING.md) 获取更多信息。
## 代码行为
本项目遵循 [代码行为](./CODE_OF_CONDUCT.md) 以确保为每个人提供一个欢迎的环境。
## 支持
如果您觉得 SSH MCP 服务器有帮助，请考虑给仓库加星或贡献！欢迎拉取请求和反馈。
