内容
# beszel-mcp
[模型上下文协议（MCP）](https://modelcontextprotocol.io) 服务器，适用于 [Beszel](https://beszel.dev) — 轻量级服务器监控平台。直接从 Claude 或任何兼容 MCP 的客户端查询服务器的健康状态、指标、容器和警报。
## 功能特点
| 工具 | 描述 |
| --- | --- |
| `list_systems` | 所有被监控的服务器，包含状态、CPU/内存/磁盘使用率、运行时间 |
| `search_systems` | 按名称、主机、状态筛选服务器（使用 PocketBase 筛选语法） |
| `get_system_stats` | 详细的 CPU、RAM、交换内存、磁盘 I/O、网络、温度等信息 |
| `list_docker_containers` | Docker/Podman 容器 — CPU、内存、健康状态、网络 |
| `list_alerts` | 活跃（已触发）的警报，或所有已配置的警报规则 |
## 前置条件
- Go 1.22+
- 运行中的 [Beszel hub](https://beszel.dev/guide/getting-started)
- Beszel 用户账户（邮箱 + 密码）
## 安装
```bash
git clone https://github.com/yourusername/beszel-mcp
cd beszel-mcp
go mod tidy
go build -o beszel-mcp .
```
## 配置
服务器完全通过环境变量配置：
| 变量 | 必需 | 描述 |
| --- | --- | --- |
| `BESZEL_URL` | 是 | Beszel hub URL，例如 `http://localhost:8090` |
| `BESZEL_EMAIL` | 是 | Beszel 用户邮箱 |
| `BESZEL_PASSWORD` | 是 | Beszel 用户密码 |
> **提示：** 管理员账户可以查看所有系统；普通用户只能查看他们拥有的系统。
## Claude Desktop 配置
将以下内容添加到您的 `claude_desktop_config.json`：
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"beszel": {
"command": "/absolute/path/to/beszel-mcp",
"env": {
"BESZEL_URL": "http://localhost:8090",
"BESZEL_EMAIL": "your@email.com",
"BESZEL_PASSWORD": "yourpassword"
}
}
}
}
```
重启 Claude Desktop。您应该在工具菜单中看到 Beszel 工具。
## Claude 代码 / 其他 MCP 客户端
直接运行：
```bash
BESZEL_URL=http://localhost:8090 \
BESZEL_EMAIL=your@email.com \
BESZEL_PASSWORD=yourpassword \
./beszel-mcp
```
或使用环境文件：
```bash
# .env
BESZEL_URL=http://localhost:8090
BESZEL_EMAIL=your@email.com
BESZEL_PASSWORD=yourpassword
```
```bash
env $(cat .env | xargs) ./beszel-mcp
```
## 示例提示
连接 Claude 后，尝试以下操作：
- _"列出所有我的服务器及其当前状态"_
- _"哪些服务器现在宕机了？"_
- _"显示我的 prod-web 服务器的 CPU 和内存状态"_
- _"列出系统 `abc123xyz` 上的所有 Docker 容器"_
- _"我应该知道有哪些活跃的警报？"_
- _"查找所有名称中包含 'nginx' 的服务器"_
- _"哪些服务器状态为宕机或暂停？"_
## 工具参考
### `list_systems`
列出所有可访问的系统。
**参数：**
- `status_filter` *(可选)* — `"up"`、`"down"`、`"paused"` 或 `"pending"`
**示例输出：**
```
Found 3 system(s):
### ✅ prod-web
ID: abc123xyz
Host: 192.168.1.10:45876
Status: up
OS: Linux
Agent: v0.18.6
CPU: 12.3%
Memory: 45.1%
Disk: 61.0%
Load: 0.85 / 0.72 / 0.68
Uptime: 14d 6h 22m
```
### `search_systems`
使用 [PocketBase 筛选语法](https://pocketbase.io/docs/api-rules-and-filters/) 筛选系统。
**参数：**
- `filter` *(必填)* — 筛选表达式
**筛选示例：**
| 目标 | 筛选 |
| --- | --- |
| 名称包含 "web" | `name~"web"` |
| 精确名称匹配 | `name="prod-db"` |
| 特定状态 | `status="down"` |
| 主机在子网中 | `host~"10.0.0"` |
| 宕机或暂停 | `status="down"\|\|status="paused"` |
### `get_system_stats`
单个系统的详细指标。
**参数：**
- `system_id` *(必填)* — 系统记录 ID
- `resolution` *(可选)* — 数据粒度：
- `"1m"` — 最近约 1 小时的 1 分钟样本
- `"10m"` — 最近约 12 小时 *(默认)*
- `"20m"` — 最近约 24 小时
- `"120m"` — 最近约 7 天
- `"480m"` — 最近约 30 天
### `list_docker_containers`
列出 Docker/Podman 容器。
**参数：**
- `system_id` *(可选)* — 限制在一个系统上；省略则为所有系统
**列：** 名称、CPU%、内存（GB）、网络（字节/秒）、健康状态、镜像
### `list_alerts`
显示警报规则及其触发状态。
**参数：**
- `all` *(可选，布尔值)* — `true` = 显示所有规则；`false`（默认）= 仅显示已触发的规则
## 架构
```
beszel-mcp/
├── main.go # 入口点，环境配置，服务器引导
├── go.mod
├── internal/
│ ├── client/
│ │ └── beszel.go # PocketBase REST 客户端，身份验证令牌缓存
│ └── tools/
│ └── tools.go # MCP 工具定义和处理程序
└── README.md
```
客户端自动处理 JWT 身份验证和令牌刷新。令牌缓存在内存中，并在过期前主动刷新。
## 安全注意事项
- 凭证通过环境变量传递，绝不硬编码
- JWT 令牌仅存储在内存中；绝不写入磁盘
- 尽可能为 MCP 服务器使用专用的只读 Beszel 用户
- 如果您的 Beszel 实例位于具有 TLS 的反向代理后面，请在 `BESZEL_URL` 中使用 `https://`
## 许可证
MIT
