Homelab MCP服务器
A. 模型上下文协议（MCP） 为管理基于Kubernetes的家庭实验室（特别是Raspberry Pi K3s集群）而设计的服务器。
此服务器为LLM（如Claude）提供了一个安全、结构化的接口，以便与您的集群、媒体服务和网络基础设施进行交互，而无需提供原始数据 kubectl 访问或不受限制的SSH功能。
🚀 特性
Kubernetes操作
- 健康检查： 监控节点、资源使用情况和问题Pod。
- 资源检查： 列出并描述部署、状态集、守护进程、Pod、服务和配置映射，并提供完整的规范详细信息。
- 储存： 检查带有状态、容量和存储类信息的持久卷索赔。
- 安全重启： 触发白名单部署的滚动重启（例如，Jellyfin、Pi hole、媒体堆栈）。
- 备份： 检查CronJob状态，检查详细的作业规范，检索作业pod日志，并手动触发备份作业。
- GitOps： 监控通量Kustomizations/HelmRelease并触发协调。
- 秘密： 查看外部机密同步状态并强制刷新（1Password集成）。
网络和DNS（Pi孔/未绑定）
- 状态： 检查DNS服务的运行状况。
- 诊断： 查看被阻止的查询统计信息、被阻止的顶级域和最近的查询日志。
- 测试： 跑
dig来自集群内的命令来验证分辨率。 - 管理层： 查看白名单并触发重力更新。
媒体服务（Jellyfin/Immich）
- 健康： 监控媒体应用程序的pod状态。
- 统计数据： 详细的库统计数据和活动会话监控。
- 管理层： 搜索媒体库并触发特定项目的元数据刷新。
网络诊断
- 节点网络： 检查任何集群节点上的接口、地址、路由和路由规则。
- 防火墙规则： 按表和链转储iptables/ip6tables规则。
- 连接跟踪： 查看带有源/目标筛选的conntrack条目。
- 入口测试： 使用详细的时间对集群内的入口URL进行卷曲。
- 连接测试： 节点和目标之间的Ping和TCP端口检查。
- Pod日志： 使用容器、时间范围和行数过滤检索pod日志。
基础设施
- 证书： 监控证书管理器证书到期和准备情况。
- NAS集成： 安全地触摸Synology NAS上的特定路径（通过SSH）以触发文件系统事件。
- 尾秤： 监控VPN连接器状态。
🔒 安全模型
该项目采用“深度防御”方法构建：
- 最低特权： 使用专用ServiceAccount运行。
- 只读： 大多数资源（Pod、事件、Flux、证书）。 - 行动范围： patch 严格限于白名单部署和Flux资源。 - 执行范围： pod/exec 严格限于 jellyfin, pihole，以及 mcp-homelab （调试代理）命名空间通过特定的角色。
- 输入验证： 对所有工具输入进行严格验证（特别是文件路径和资源名称）。
- 身份验证： 需要
X-API-Key所有请求的标头。 - 网络： 设计用于在只能通过Tailscale进入的Ingress后面运行。
🛠️ 配置
环境变量
| 变量 | 描述 | 必填 |
|---|---|---|
MCP_API_KEY | 用于验证请求的密钥 | 是 |
MCP_TRANSPORT | stdio （默认）或 sse | 没有 |
NAS_HOST | Synology NAS的主机名/IP | 是（适用于NAS工具） |
NAS_USER | NAS的SSH用户名 | 是（适用于NAS工具） |
NAS_PRIVATE_KEY | NAS的SSH私钥 | 是（适用于NAS工具） |
NAS_ALLOWED_PATHS | 逗号分隔的允许路径前缀列表 | 否（默认为严格子集） |
JELLYFIN_URL | Jellyfin的内部URL | 否（默认值：cluster-svc） |
JELLYFIN_API_KEY | API Jellyfin操作密钥 | 是（用于媒体工具） |
IMMICH_API_KEY | 用于Imich统计的API密钥 | 是（用于媒体工具） |
BAZARR_URL | Bazarr的内部URL | 否（默认值：cluster-svc） |
BAZARR_API_KEY | API Bazarr操作密钥 | 是（用于字幕工具） |
SONARR_URL | Sonarr的内部URL | 否（默认值：cluster-svc） |
SONARR_API_KEY | Sonarr操作的API密钥 | 是（适用于电视工具） |
RADARR_URL | Radarr的内部URL | 否（默认值：群集svc） |
RADARR_API_KEY | Radarr操作的API密钥 | 是（适用于电影工具） |
SABNZBD_URL | SABnzbd的内部URL | 否（默认值：集群svc） |
SABNZBD_API_KEY | 用于SABnzbd操作的API密钥 | 是（用于下载工具） |
📦 部署
地方发展（Stdio）
# Install dependencies
npm install
# Build
npm run build
# Run in stdio mode (for testing with Claude Desktop/CLI)
npm run devKubernetes（生产）
服务器被设计为在集群中部署为Pod。
- 构建Docker镜像：
docker build -t ghcr.io/username/homelab-mcp:latest .- 部署清单：
请参阅 k8s/ 例如清单目录，包括：
- deployment.yaml - service.yaml - ingress.yaml （为Tailscale/Cert管理器配置） - clusterrole.yaml （RBAC权限范围）
🧩 可用工具
| 类别 | 工具 |
|---|---|
| 簇 | get_cluster_health, restart_deployment |
| 域名系统 | get_dns_status, test_dns_query, update_pihole_gravity, get_pihole_whitelist, get_pihole_queries |
| GitOps | get_flux_status, reconcile_flux |
| 媒体 | get_media_status, fix_jellyfin_metadata |
| 字幕 | get_subtitle_status, get_subtitle_history, search_subtitles |
| 电视（Sonarr） | get_sonarr_queue, get_sonarr_history, search_sonarr_episode |
| 电影（拉达） | get_radarr_queue, get_radarr_history, search_radarr_movie |
| 下载（SABnzbd） | get_sabnzbd_queue, get_sabnzbd_history, retry_sabnzbd_download, pause_resume_sabnzbd |
| Arr共享 | get_quality_profile, reject_and_search |
| 备份 | get_backup_status, trigger_backup, get_cronjob_details, get_job_logs |
| 秘密 | get_secrets_status, refresh_secret |
| 存储 | get_pvcs |
| 资源 | describe_resource |
| 系统 | get_certificate_status, get_ingress_status, touch_nas_path |
| 网络 | get_node_networking, get_iptables_rules, get_conntrack_entries, curl_ingress, test_pod_connectivity |
| 日志 | get_pod_logs |