AI导哈

Kubernetes集群管理服务器

一个专为Kubernetes家庭实验室设计的服务器，提供安全的结构化接口，让LLMs（如Claude）与集群、媒体服务和网络基础设施交互，而无需提供原始kubectl访问或无限制的SSH能力。

  • by mtgibbs
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 mtgibbs/pi-cluster-mcp

使用说明

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连接器状态。

🔒 安全模型

该项目采用“深度防御”方法构建：

  1. 最低特权： 使用专用ServiceAccount运行。
    • 只读： 大多数资源（Pod、事件、Flux、证书）。
    • 行动范围： patch 严格限于白名单部署和Flux资源。
    • 执行范围： pod/exec 严格限于 jellyfin, pihole，以及 mcp-homelab （调试代理）命名空间通过特定的角色。
  2. 输入验证： 对所有工具输入进行严格验证（特别是文件路径和资源名称）。
  3. 身份验证： 需要 X-API-Key 所有请求的标头。
  4. 网络： 设计用于在只能通过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密钥 是（用于下载工具）
MEALIE_URL Mealie的内部URL 否（默认值：cluster-svc）
MEALIE_API_TOKEN Mealie操作的API令牌 是（用于配方工具）
MEALIE_PUBLIC_URL 配方链接的公共基础URL 否（默认值：recipes.lab.mtgibbs.dev）
MEALIE_GROUP_SLUG 配方web链接中使用的组块 否（默认值：主页）

📦 部署

地方发展（Stdio）

# Install dependencies
npm install

# Build
npm run build

# Run in stdio mode (for testing with Claude Desktop/CLI)
npm run dev

Kubernetes（生产）

服务器被设计为在集群中部署为Pod。

  1. 构建Docker镜像：

    docker build -t ghcr.io/username/homelab-mcp:latest .

  2. 部署清单： 看 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
食谱（Mealie） get_mealie_status, search_mealie_recipes, get_mealie_recipe, import_mealie_recipe_url, parse_mealie_recipe_ingredients
备份 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

相关 MCP