内容
# Termix MCP 服务器
一个 [MCP](https://modelcontextprotocol.io) 服务器，允许 Claude（或其他 MCP 客户端）通过其 REST API 与自行托管的 [Termix](https://github.com/Termix-SSH/Termix) 实例进行通信，Termix 是一个开源的 SSH 客户端/服务器管理工具。
这是一个社区/非官方项目，与 Termix 团队无关。
## 功能
| 工具 | 描述 |
|---|---|
| `list_ssh_hosts` | 列出所有已保存的 SSH 主机 |
| `get_ssh_host` | 通过 ID 获取主机 |
| `create_ssh_host` | 创建新主机 |
| `update_ssh_host` | 更新主机 |
| `delete_ssh_host` | 删除主机 |
| `get_all_host_statuses` | 所有主机的在线/离线状态 |
| `get_host_status` | 主机的状态 |
| `get_host_metrics` | 主机的 CPU/内存/磁盘/网络指标 |
| `list_tunnel_statuses` | 所有 SSH 隧道的狀態 |
| `get_tunnel_status` | 隧道的狀態 |
| `connect_ssh_tunnel` | 启动已配置的隧道 |
| `disconnect_ssh_tunnel` | 停止隧道 |
| `get_recent_activity` | 最近的活动日志 |
| `get_active_alerts` / `get_dismissed_alerts` | 警报状态 |
Docker 容器管理（列出/启动/停止/重启）**不**作为工具公开：它在实时后端通过有状态的 SSH 会话 + Socket.IO 通道运行，而不是普通的 REST 请求/响应，因此它不适合此服务器的简单逐工具模型。在与实际 Termix 后端源代码验证后（参见下面的“注意和警告”），它被删除；本 README 的早期版本曾宣传过它，但它实际上从未针对真实实例工作过。
## 要求
- Node.js 18+
- 一个正在运行的、自行托管的 Termix 实例（参见 [Termix 安装文档](https://docs.termix.site/install/)）
- 一个 Termix API 密钥（参见下文）
## 创建 Termix API 密钥
在 Termix v2.5.0 上验证通过。
1. 登录到您的 Termix 网页界面。
2. 点击侧边栏左下角的用户名，然后选择 **用户配置文件**。
3. 打开 **API 密钥** 选项卡（在用户配置文件页面的左侧面板中）。
4. 点击 **新建密钥**。
5. 为其命名（例如 `mcp-server`），并可选地设置过期日期（`dd-mm-jjjj` 字段 - 留空表示密钥不会过期）。
6. 点击 **创建密钥**。
**已知怪癖：** 在此处测试的版本（v2.5.0）中，Termix **不** 在创建后在 UI 中显示或让您复制完整的密钥值 - 仅显示一个短前缀（`tmx_xxxxxxxx…`）用于标识。如果您的版本表现相同，请查看 [Termix GitHub 仓库](https://github.com/Termix-SSH/Termix)（问题/版本）以获取当前推荐的获取可用密钥值的方法 - 这可能是 UI 差距，可能会修复，或者根据您的版本，可能存在替代流程（例如，通过设置向导或配置/CLI 选项）。如果 API 密钥不可用，则 JWT 持有者令牌（通过登录获得）是一个有效的备用方案 - 参见 Termix API 文档的身份验证部分获取详细信息。
每个密钥都继承创建该密钥的用户的权限，并且在每个请求上作为 `Authorization: Bearer <key>` 发送 - 这正是此 MCP 服务器执行的操作（参见下面的 `TERMIX_API_KEY`）。
## 设置
```bash
git clone <您的仓库 URL> termix-mcp
cd termix-mcp
npm install
npm run setup
```
`npm run setup` 运行一个交互式提示，询问您的 Termix URL 和 API 密钥，并为您写入本地 `.env` 文件（git 忽略，因此永远不会提交）。这是开始使用最简单的方法。
如果您不想使用交互式提示，请手动执行：
```bash
cp .env.example .env
# 编辑 .env 并填写 TERMIX_BASE_URL 和 TERMIX_API_KEY
```
`TERMIX_BASE_URL` 是 Termix **后端 API** 的基本 URL，而不是网页界面 - 对于默认的本地 Docker 安装，这通常是 `http://localhost:30001`；如果您更改了端口或在反向代理后面运行，请调整。
Termix 的后端实际上分布在几个独立的服务中，运行在不同的端口上，通过直接读取 Termix 后端源代码确认（托管的 API 文档对自动获取返回 403，并且与实时 v2.5.0 实例实际执行的操作不完全匹配）：
| 服务 | 默认端口 | 用途 |
|---|---|---|
| 主 API | 30001 (`TERMIX_BASE_URL`) | SSH 主机 CRUD，警报 |
| 指标 API | 30005 (`TERMIX_METRICS_URL`) | 主机在线/离线状态，实时指标 |
| 仪表板 API | 30006 (`TERMIX_DASHBOARD_URL`) | 最近的活动日志 |
| 隧道 API | 30003 (`TERMIX_TUNNEL_URL`) | SSH 隧道状态/连接/断开 |
您只需要设置 `TERMIX_BASE_URL`（+ `TERMIX_API_KEY`）- 其他三个默认设置为与 `TERMIX_BASE_URL` 相同的宿主，端口交换，这与股票 Termix 部署匹配。仅当您的设置将这些服务暴露在不同的主机/端口上（例如，在具有自定义路由的反向代理后面）时，才显式设置它们。
### 直接运行
```bash
npm start
```
服务器通过 stdio 通信，因此它旨在由 MCP 客户端（Claude Desktop，Claude Code 等）启动，而不是在终端中独立运行以进行交互式使用。
### 在 Claude Desktop 中配置
添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"termix": {
"command": "node",
"args": ["/绝对路径/到/termix-mcp/src/index.js"],
"env": {
"TERMIX_BASE_URL": "http://localhost:30001",
"TERMIX_API_KEY": "您的_termix_api_key_在此"
}
}
}
}
```
重启 Claude Desktop 后。如果您已经运行了 `npm run setup`（创建了一个 `.env` 文件），您可以完全省略 `"env"` 块 - 服务器会自动加载 `.env`。
### 在 Claude Code 中配置
```bash
claude mcp add termix -- node /绝对路径/到/termix-mcp/src/index.js
```
然后在您的 shell 环境或 MCP 服务器配置中设置 `TERMIX_BASE_URL` / `TERMIX_API_KEY`，按照 Claude Code 文档。
## 注意和警告
- 当前连接的所有端点（`/host/db/host`，`/status`，`/metrics/:id`，`/ssh/tunnel/*`，`/activity/recent`，`/alerts`）都经过了实时 Termix v2.5.0 实例的验证 - 通过读取实际的后端路由定义 [Termix 源代码](https://github.com/Termix-SSH/Termix/tree/main/src/backend) 和进行真实的身份验证请求。托管的 API 文档（`docs.termix.site`）对自动获取返回 403，在本项目的早期版本中，一些假设的路径/端口在与真实后端检查时被证明是错误的 - 如果它们不同意，请相信源代码和您自己的实时实例，而不是文档站点。
- `create_ssh_host` 接受主机主体的自由格式 JSON 对象，因为模式根据身份验证类型（密码，密钥，凭证引用，Tailscale 等）变化很大 - 在您的实例上检查现有主机以获取具体示例。`update_ssh_host` 的主体形状未经过独立验证，仅限于“与创建相同” - 如果字段似乎不适用，请首先检查真实主机对象。
- 破坏性工具（`delete_ssh_host`，`disconnect_ssh_tunnel`）作为常规工具公开，无需额外的确认步骤 - 如果您将其连接到自主代理，请考虑在客户端/代理策略中控制这些。
- 无分页/筛选助手；响应直接从 Termix API 返回。
## 扩展
分两步添加新端点：
1. 在 `src/termix-client.js` 中为 `termix` 添加一个方法，该方法调用其中一个服务助手（`main`，`metrics`，`dashboard`，`tunnel`）并带有 `(method, path, { query, body })` - 选择拥有该路由的服务（参见上面的端口表，或检查 [Termix 源代码](https://github.com/Termix-SSH/Termix/tree/main/src/backend) 如果您不确定）。
2. 在 `src/index.js` 中注册一个调用它的 `server.tool(...)`。
在验证后端源代码或实时请求之前，请勿信任来自托管文档站点的路由名称/路径 - 这就是导致该项目初始发货的路径不正确的原因。
## 许可证
MIT - 参见 [LICENSE](./LICENSE)。
