内容
# mcp-it-ops
MCP 服务器，负责向 Claude 公开 homelab 和 IT-ops 工具。设计为逐一添加工具，首先从 Linux homelab 中可测试的工具开始，然后扩展到 AD / Intune / M365，当有企业测试环境时。
> **状态：v0.0.5（2026-04-19）** — 8 个可用工具，37 个 pytest 测试，Python 3.10/3.11/3.12 下 CI 绿色通过。工具按类别模块化，位于 `tools/` 下。在 niborserver 上本地测试通过。尚未发布到 PyPI；需从源码安装。
## 当前功能
安装并连接到 Claude（桌面版或代码版）后，Claude 可以调用：
| 工具 | 功能 |
|---|---|
| `get_system_health` | 获取本地主机的主机名、运行时间、1分钟负载、内存使用率、根磁盘使用率和运行容器数量。读取 `/proc` 并调用 `df` 和 `docker ps`。 |
| `get_grafana_alert_state` | 查询 Grafana Prometheus 风格的规则 API，返回按状态分组的警报（触发 / 待定 / 不活跃 / 无数据 / 错误），包含名称、文件夹、健康状态、最后评估时间和注解。 |
| `get_freqtrade_bot_status(bot)` | 从 freqtrade REST API 获取利润、胜率、开放交易数量和余额。机器人名称通过配置解析。 |
| `get_container_status` | 解析完整的 `docker ps` 输出为结构化的容器记录（名称、镜像、状态、健康状态、运行时间、端口）。 |
| `query_loki_logs(query, since, limit)` | 对 `localhost:3100` 的 Loki LogQL `query_range` 查询，返回结构化的日志流和日志行，限制在 1000 条以内。 |
| `get_smartd_health(device='/dev/nvme0n1')` | 通过 `sudo smartctl -a` 获取 NVMe/SATA SMART 健康状态，包括整体健康状态、关键警告、温度、可用备用空间、已使用百分比、开机时间、不安全关机次数和媒体错误。 |
| `get_backup_status` | 读取 `/var/log/niborserver-backup.log`，报告最后一次备份的运行时间、完成时间、持续时间、大小和成功状态。 |
| `query_influxdb_flux(flux, bucket)` | 在本地 InfluxDB v2 上执行 Flux 查询，返回解析后的 CSV 记录（限制在 500 行以内）。通过 `INFLUXDB_TOKEN` 和 `INFLUXDB_ORG` 环境变量进行身份验证。 |
## 未来规划
- `get_uptime_kuma_status` — 通过 Uptime Kuma API 拉取监控状态
- HTTP 传输，以便 openclaw / 其他 tailnet 对等节点可以查询驻留在 niborserver 上的工具（目前仅限标准输入输出）
- _最终目标_：`get_ad_user`、`get_intune_compliance`、`get_m365_service_health` — 当有企业测试环境时
## 快速开始
### 在 MCP 服务器运行的主机上
```bash
git clone https://github.com/bastiaan365/mcp-it-ops.git
cd mcp-it-ops
python3 -m venv .venv
.venv/bin/pip install -e .
```
### 配置
复制示例配置文件并自定义：
```bash
cp config/settings.example.yaml config/settings.yaml
# 编辑 config/settings.yaml — 指向您的 Grafana、freqtrade 机器人等
```
机密信息来自环境变量，而非 YAML 配置文件。默认环境变量名称：
| 环境变量 | 功能 |
|---|---|
| `GRAFANA_PASSWORD` | Grafana 管理员密码（从 `grafana.password_env` 引用） |
| `FT_STEADY_USER` / `FT_STEADY_PASS` | freqtrade 机器人 1 的基本身份验证 |
| `FT_FUN_USER` / `FT_FUN_PASS` | freqtrade 机器人 2 的基本身份验证 |
### 连接到 Claude 桌面版
在 macOS 上添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`，在 Windows 上添加到 `%APPDATA%/Claude/claude_desktop_config.json：
```json
{
"mcpServers": {
"it-ops": {
"command": "/path/to/mcp-it-ops/.venv/bin/mcp-it-ops",
"env": {
"GRAFANA_PASSWORD": "your-grafana-password",
"MCP_IT_OPS_CONFIG": "/path/to/mcp-it-ops/config/settings.yaml"
}
}
}
}
```
重启 Claude 桌面版。工具将出现在 "it-ops" 下。
### 无 Claude 的烟雾测试
```bash
GRAFANA_PASSWORD=... .venv/bin/python -c "
from mcp_it_ops.server import get_system_health, get_grafana_alert_state
import json
print(json.dumps(get_system_health(), indent=2))
print(json.dumps(get_grafana_alert_state().get('summary'), indent=2))
"
```
或使用官方 MCP 检查工具：
```bash
.venv/bin/python -m mcp dev src/mcp_it_ops/server.py
```
## 要求
- Python 3.10+
- `mcp>=1.27.0`、`httpx>=0.27`、`pyyaml>=6.0`（自动安装）
- 读取 `/proc`、`df`、`docker ps` 以获取 `get_system_health`
- 服务的网络可达性和凭证
## 开发方式
- `src/mcp_it_ops/server.py` — 所有工具定义
- `tests/` — pytest 测试；每个工具一个文件（待补充）
- `config/settings.example.yaml` — 提交的模板；`config/settings.yaml` 被 gitignore
添加工具时，请参阅 [`CLAUDE.md`](./CLAUDE.md) 获取工作流程和设计约定。
## 许可证
MIT
