内容
# homelab-mcp
[](https://github.com/Nainounen/homelab-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/homelab-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
<br>
<img src="assets/banner.png" alt="homelab-mcp banner" width="800">
MCP 服务器，为 AI 助手提供对 Proxmox homelab 的完全控制权 — 管理虚拟机和容器，部署 Docker 项目，监控服务，控制媒体栈，检查存储健康状况，所有这些都可以通过对话实现。
**17 个领域中的 65+ 种工具。** 模块化架构，设计用于 AI 辅助扩展。
## AI 设置
**无需手动配置。** 服务器包含一个 AI 原生设置向导。只需将其连接到您的 MCP 客户端，然后说：
> "设置我的 homelab" 或 "配置 MCP 服务器"
设置向导会扫描您的配置，通过交互式方式引导您完成每个设置，保存您的答案，并验证连接性 — 所有这些都通过对话实现。凭证永远不会暴露给 AI；向导会屏蔽密码、API 密钥和令牌，然后再返回任何结果。
## 快速开始
### 先决条件
- **Node.js 20+**
- 可通过网络访问的 Proxmox VE 主机
- 开发箱（任何可通过 SSH 访问且运行 Docker 的 Linux 主机）
- （可选）媒体服务：Plex、Radarr、Sonarr、SABnzbd、Overseerr、Prowlarr
- （可选）监控：Prometheus、Grafana、Uptime Kuma
### 安装
**从 npm（推荐）：**
```bash
npm install -g homelab-mcp
# 或在您的项目中本地安装：
npm install homelab-mcp
```
**从源码（适用于贡献者）：**
```bash
git clone https://github.com/Nainounen/homelab-mcp.git
cd homelab-mcp
npm install
npm run build
```
### Docker（可选）
提供了用于容器化部署的 Dockerfile：
```bash
npm run build
cp .env.example .env # 使用您的凭证编辑
docker compose up -d
```
对于大多数用户，直接使用 Node.js（不使用 Docker）运行更简单 — MCP 服务器通过 stdio 进行通信。
### 连接到您的 MCP 客户端
添加到您的 MCP 客户端配置文件中。对于 Claude Code，配置文件位于 `~/.claude/claude_mcp_config.json`:
```json
{
"mcpServers": {
"homelab": {
"command": "npx",
"args": ["homelab-mcp"],
"cwd": "/path/to/your/homelab-config"
}
}
}
```
将您的 `.env` 文件放在 `cwd` 目录中（复制此存储库中的 `.env.example` 作为起点）。MCP 配置中不包含任何机密；服务器从其工作目录加载 `.env`。
然后只需说 **"设置我的 homelab"** — AI 原生设置向导将引导您完成其余操作。
## 配置
所有设置都存储在 `.env` 中。有关完整模板，请参见 `.env.example`。服务器启动时会配置您启用的服务 — 如果缺少任何服务的环境变量，则会跳过并显示警告。
### 必需（如果缺少这些，服务器将无法启动）
| 变量 | 描述 |
|---|---|
| `PROXMOX_HOST`, `PROXMOX_PORT`, `PROXMOX_USER`, `PROXMOX_NODE` | Proxmox API 访问 |
| `PROXMOX_PASSWORD` 或 `PROXMOX_KEY_PATH` | Proxmox 身份验证 |
| `DEVBOX_HOST`, `DEVBOX_USER` | 开发箱 SSH 访问 |
| `DEVBOX_PASSWORD` 或 `DEVBOX_KEY_PATH` | 开发箱 SSH 身份验证 |
| `RADARR_URL`, `RADARR_API_KEY` | Radarr API |
| `SONARR_URL`, `SONARR_API_KEY` | Sonarr API |
| `PROWLARR_URL`, `PROWLARR_API_KEY` | Prowlarr API |
| `SABNZBD_URL`, `SABNZBD_API_KEY` | SABnzbd API |
| `OVERSEERR_URL`, `OVERSEERR_API_KEY` | Overseerr API |
### 可选（如果缺少，则会跳过并显示警告）
| 变量 | 服务 |
|---|---|
| `QNAP_HOST`, `QNAP_USER`, `QNAP_PASSWORD` 或 `QNAP_KEY_PATH` | QNAP NAS |
| `PLEX_URL`, `PLEX_TOKEN` | Plex |
| `TAUTULLI_URL`, `TAUTULLI_API_KEY` | Tautulli 分析 |
| `BAZARR_URL`, `BAZARR_API_KEY` | Bazarr 字幕 |
| `ADGUARD_URL`, `ADGUARD_USER`, `ADGUARD_PASSWORD` | AdGuard Home |
| `PBS_URL`, `PBS_TOKEN_ID`, `PBS_TOKEN_SECRET` | Proxmox Backup Server |
| `LIDARR_URL`, `LIDARR_API_KEY` | Lidarr 音乐 |
| `READARR_URL`, `READARR_API_KEY` | Readarr 书籍 |
| `UPTIME_KUMA_URL`, `UPTIME_KUMA_USER`, `UPTIME_KUMA_PASSWORD` | Uptime Kuma |
| `PROMETHEUS_URL` | Prometheus API |
| `GRAFANA_URL`, `GRAFANA_TOKEN` | Grafana API |
| `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` | Telegram 通知 |
### 安全设置
| 变量 | 默认值 | 描述 |
|---|---|---|
| `SSH_STRICT_HOST_KEY` | `false` | 设置为 `true` 以启用 `known_hosts` 验证 |
| `PROXMOX_TLS_VERIFY` | `false` | 设置为 `true` 以验证 Proxmox TLS 证书 |
| `PBS_TLS_VERIFY` | `false` | 设置为 `true` 以验证 PBS TLS 证书 |
### 调整
| 变量 | 默认值 | 描述 |
|---|---|---|
| `MAX_OUTPUT_CHARS` | `30000` | 每个工具结果的最大字符数（`0` 禁用截断） |
| `HTTP_RETRIES` | `3` | 暂时性 HTTP 失败的重试次数（`0` 禁用） |
| `DEVBOX_CMD_TIMEOUT` | `30000` | 开发箱 SSH 命令超时（毫秒） |
| `PROXMOX_CMD_TIMEOUT` | `60000` | Proxmox SSH 命令超时（毫秒） |
## 工具参考
### 基础设施
| 工具 | 描述 |
|---|---|
| `proxmox_list_nodes` | 列出 Proxmox 节点，包含 CPU、RAM、运行时间 |
| `proxmox_list_vms` | 列出所有虚拟机和 LXC 容器 |
| `proxmox_start_vm` | 启动虚拟机或容器 |
| `proxmox_stop_vm` | 停止虚拟机或容器 |
| `proxmox_restart_vm` | 重启虚拟机或容器 |
| `proxmox_get_metrics` | 获取虚拟机/容器的详细指标 |
| `proxmox_get_node_metrics` | 节点级别的 CPU、RAM、磁盘、负载 |
| `proxmox_create_ct` | 创建新的 Debian 12 LXC 容器 |
| `proxmox_get_logs` | 获取虚拟机/容器的任务日志 |
| `proxmox_exec` | 在 Proxmox 主机上运行 shell 命令（阻止危险命令） |
### 开发箱和 Docker
| 工具 | 描述 |
|---|---|
| `devbox_exec` | 在开发箱上运行 shell 命令（阻止危险命令） |
| `devbox_read_file` | 读取文件（最大 100 KB） |
| `devbox_write_file` | 写入文件，自动创建父目录（最大 1 MB） |
| `devbox_list_dir` | 列出目录内容 |
| `devbox_docker_ps` | 显示正在运行的 Docker 容器 |
| `devbox_docker_compose` | 运行 compose up/down/restart/pull/logs |
| `devbox_git` | Git 状态、拉取、日志或克隆仓库 |
| `devbox_project_deploy` | 部署：git 拉取 → compose 拉取 → compose up → 状态 |
| `devbox_project_status` | 部署项目的健康检查 |
| `devbox_project_list` | 扫描基路径以查找 compose 项目 |
### 媒体 — 下载和库
| 工具 | 描述 |
|---|---|
| `radarr_search_movie` | 按标题搜索电影 |
| `radarr_add_movie` | 添加电影并触发下载搜索 |
| `radarr_list_movies` | 列出电影及其下载状态（筛选/搜索/限制） |
| `radarr_remove_movie` | 删除电影（可选删除文件） |
| `radarr_get_queue` | 正在下载的电影进度 |
| `radarr_force_search` | 重新搜索索引器获取电影 |
| `radarr_get_history` | 最近的下载历史 |
| `radarr_check_releases` | 显示可用的版本和拒绝的版本 |
| `radarr_clear_queue` | 从下载队列中移除所有项目 |
| `radarr_clear_blocklist` | 清除发布阻止列表 |
| `radarr_blocklist_release` | 阻止列表中添加不良版本并重试 |
| `radarr_list_path_mappings` | 列出远程路径映射 |
| `radarr_set_path_mapping` | 添加/更新路径映射 |
| `sonarr_search_series` | 按标题搜索电视剧 |
| `sonarr_add_series` | 添加电视剧并触发下载 |
| `sonarr_list_series` | 列出电视剧及其剧集进度（筛选/搜索/限制） |
| `sonarr_remove_series` | 删除电视剧（可选删除文件） |
| `sonarr_get_queue` | 正在下载的剧集进度 |
| `sonarr_force_search` | 重新搜索缺失的剧集 |
| `sonarr_season_search` | 搜索特定季度 |
| `sonarr_check_releases` | 显示季度的版本和拒绝情况 |
| `sonarr_blocklist_release` | 阻止列表中添加失败的下载并重试 |
| `sonarr_clear_queue` | 清除下载队列 |
| `sonarr_clear_blocklist` | 清除发布阻止列表 |
| `sonarr_list_path_mappings` | 列出远程路径映射 |
| `sonarr_set_path_mapping` | 添加/更新路径映射 |
| `sabnzbd_get_status` | 下载速度、ETA、磁盘空间、队列大小 |
| `sabnzbd_list_queue` | 正在下载的 NZB 文件进度 |
| `sabnzbd_get_history` | 最近的下载历史 |
| `sabnzbd_pause_queue` | 暂停下载 |
| `sabnzbd_resume_queue` | 恢复下载 |
| `sabnzbd_delete_item` | 按 NZO ID 删除队列项目 |
| `prowlarr_list_indexers` | 列出索引器及其状态 |
| `prowlarr_sync_apps` | 将索引器同步到 Radarr/Sonarr |
| `prowlarr_test_indexers` | 测试所有（或一个）索引器 |
| `lidarr_search_artist` | 搜索音乐艺术家 |
| `lidarr_add_artist` | 将艺术家添加到 Lidarr |
| `lidarr_list_artists` | 列出所有艺术家及其专辑数量 |
| `lidarr_remove_artist` | 删除艺术家 |
| `lidarr_get_queue` | 正在下载的音乐进度 |
| `readarr_search_book` | 搜索书籍 |
| `readarr_add_book` | 将书籍添加到 Readarr |
| `readarr_list_books` | 列出所有书籍 |
| `readarr_get_queue` | 正在下载的书籍进度 |
### 媒体 — Plex 和请求
| 工具 | 描述 |
|---|---|
| `plex_get_libraries` | 列出 Plex 库及其项目数量 |
| `plex_search` | 跨所有库进行搜索 |
| `plex_get_sessions` | 谁正在流媒体播放，什么，转换/直接播放 |
| `plex_recently_added` | 最近添加的电影和剧集 |
| `plex_refresh_library` | 触发库扫描 |
| `plex_delete_media` | 按 ratingKey 永久删除 |
| `plex_get_watch_history` | 跨用户的最近观看历史 |
| `seerr_list_requests` | 列出家庭媒体请求 |
| `seerr_approve_request` | 批准待处理请求 |
| `seerr_decline_request` | 拒绝请求 |
| `seerr_delete_request` | 删除请求 |
| `seerr_stats` | 请求统计 |
| `tautulli_get_activity` | 当前 Plex 流媒体（Tautulli） |
| `tautulli_get_history` | Plex 观看历史（Tautulli） |
| `tautulli_get_stats` | 30 天播放统计 |
| `bazarr_status` | 想要的字幕数量 |
| `bazarr_download_subtitle` | 触发手动字幕下载 |
### 媒体 — 运行
| 工具 | 描述 |
|---|---|
| `media_status` | 运行的容器状态和运行时间 |
| `media_logs` | 媒体容器的尾日志 |
| `media_restart` | 重启媒体容器 |
| `media_dashboard` | 一站式：Proxmox、容器、下载、库、存储、GPU |
| `nvidia_status` | GPU 温度、利用率、VRAM、功耗 |
| `security_status` | SSH 配置和 Proxmox 防火墙状态 |
### 监控和可观察性
| 工具 | 描述 |
|---|---|
| `prometheus_snapshot` | 快速的 CPU、RAM、磁盘、网络、容器健康状况 |
| `prometheus_query` | 运行任意 PromQL 查询 |
| `prometheus_range_query` | 历史指标趋势 |
| `grafana_list_dashboards` | 列出所有仪表盘 |
| `grafana_get_dashboard` | 获取仪表盘的面板列表 |
| `grafana_query_panel` | 查询面板的实际数据 |
| `uptime_status` | 监控在线/离线状态和延迟 |
### 存储、网络和 DNS
| 工具 | 描述 |
|---|---|
| `qnap_status` | QNAP NAS：RAID、驱动器温度、存储 |
| `qnap_disk_health` | 每个驱动器的 SMART 健康状况 |
| `qnap_storage_usage` | 按共享存储和使用 LVM |
| `qnap_raid_status` | RAID 数组健康检查 |
| `pbs_status` | PBS 数据存储使用情况 |
| `pbs_list_snapshots` | 最近的备份快照 |
| `pbs_get_tasks` | 备份/验证/GC 任务历史 |
| `adguard_stats` | DNS 查询统计和阻塞率 |
| `adguard_check_host` | 检查域名是否被阻止 |
| `adguard_toggle_protection` | 启用/禁用 DNS 过滤 |
| `wol_send` | Wake-on-LAN 魔法包 |
| `tailscale_status` | Tailscale 对等体和状态 |
### 更新、通知和元
| 工具 | 描述 |
|---|---|
| `container_check_updates` | 检查较新的 Docker 镜像 |
| `container_update` | 拉取 + 重启容器 |
| `notify_telegram` | 发送消息到 Telegram |
| `homelab_health` | ping 所有配置的服务，报告可达/下 + 延迟 |
| `homelab_capabilities` | **开始这里** — 列出所有可用工具 |
| `homelab_setup` | **AI 引导设置向导** — 通过对话配置 `.env` |
## 架构
```
src/
├── {service}.ts # 层 1：HTTP/SSH 客户端工厂
├── tools/{service}.ts # 层 2：Zod 模式 + 实现
├── modules/{service}.ts # 层 3：工具定义 + 处理器路由器
├── modules/registry.ts # 中央模块注册表
└── index.ts # MCP 服务器入口点
```
每个集成都遵循相同的三文件模式。添加新服务意味着创建这三个文件，并在注册表中注册它。脚手架脚本处理样板：
```bash
npm run new-module -- tautulli```
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取完整指南。
## 安全
- **凭证**: 所有机密存储在 `.env` 中，该文件被 gitignore。永远不要提交它。
- **SSH 主机密钥**：默认情况下验证关闭（homelab 主机经常更改密钥）。设置为 `SSH_STRICT_HOST_KEY=true` 以启用它。
- **TLS**：Proxmox/PBS 自签名证书 - 默认情况下验证关闭。如果您有受信任的证书，请设置 `PROXMOX_TLS_VERIFY=true` / `PBS_TLS_VERIFY=true`。
- **命令安全**：`exec` 工具阻止破坏性命令（`rm -rf /`、`mkfs`、`shutdown` 等）。
- **错误清理**：返回给 MCP 客户端的错误消息被清理 - 完整详细信息会输出到 stderr。
参见 [SECURITY.md](SECURITY.md) 获取详细信息。
## 许可证
MIT - 参见 [LICENSE](LICENSE)。
