AI导哈

模块化家庭实验室服务管理协议

Homelab MCP是一个模块化的模型上下文协议服务器，为家庭实验室服务提供统一的管理接口，支持多种服务的集成与监控。

  • by HavartiBard
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 HavartiBard/homelab-mcp

使用说明

家庭实验室MCP

用于家庭实验室服务管理的模块化MCP（模型上下文协议）服务器。通过单个MCP接口提供对多个家庭实验室服务的统一访问。

特性

  • 模块化架构：仅启用所需的服务
  • 统一健康检查：从一个端点监视所有服务
  • Docker就绪：轻松部署到Unraid、Proxmox或Kubernetes
  • 可扩展：易于添加新的服务集成

支持服务列表

服务 描述 状态
Nginx代理管理器 反向代理管理，SSL证书 ✅ 准备好了
Pi孔 DNS广告拦截，查询统计信息 ✅ 准备好了
正常运行时间Kuma 服务可用性监控 ✅ 准备好了
波特纳 跨主机的Docker管理 ✅ 准备好了
UPS坚果 UPS电源监控 ✅ 准备好了
Netgear奥比 WiFi网状系统管理 ✅ 准备好了
AdGuard主页 DNS广告拦截替代方案 ✅ 准备好了
技术 DNS服务器管理 ✅ 准备好了
NetBox DCIM/IPAM网络文档 ✅ 准备好了

快速开始

1.克隆和配置

git clone https://github.com/HavartiBard/homelab-mcp.git
cd homelab-mcp

# Copy and edit configuration
cp config.example.yaml config.yaml
# Edit config.yaml with your service URLs and credentials

2.使用Docker运行

docker compose up -d

3.本地运行（开发）

# Install dependencies
pip install -e .

# Run server
python -m homelab_mcp.main

配置

编辑 config.yaml 要启用服务和配置凭据，请执行以下操作：

server:
  host: "0.0.0.0"
  port: 6971
  transport: "streamable-http"

services:
  nginx_proxy_manager:
    enabled: true
    url: "http://192.168.1.100:81"
    username: "admin@example.com"
    password: "your-password"

  pihole:
    enabled: true
    url: "http://192.168.1.53"
    api_key: "your-api-key"

  # ... more services

可用工具

核心工具

  • homelab_health_check -检查所有已启用服务的运行状况
  • homelab_list_services -列出已配置的服务和状态

Nginx代理管理器

  • npm_list_proxy_hosts -列出所有代理主机
  • npm_list_ssl_certificates -列出SSL证书
  • npm_get_proxy_host -获取代理主机详细信息
  • npm_enable_proxy_host / npm_disable_proxy_host -切换主机
  • npm_check_expiring_certificates -查找过期的SSL证书

Pi孔

  • pihole_get_summary -DNS查询统计
  • pihole_get_top_queries / pihole_get_top_blocked -顶级域名
  • pihole_enable / pihole_disable -切换广告拦截
  • pihole_get_query_types -查询类型细分

正常运行时间Kuma

  • uptime_get_status_page -获取状态页面信息
  • uptime_get_heartbeats -监测心跳数据
  • uptime_get_monitor_summary -所有监视器摘要

波特纳

  • portainer_list_endpoints -列出Docker环境
  • portainer_list_containers -列出端点上的容器
  • portainer_get_endpoint_stats -容器/图像/体积统计
  • portainer_container_action -启动/停止/重新启动容器
  • portainer_list_stacks -列出docker组合堆栈

UPS坚果

  • ups_get_status -电池、负载、运行时间信息
  • ups_get_all_variables -所有UPS变量
  • ups_list_devices -列出UPS设备
  • ups_check_power_status -快速电源状态检查

Netgear奥比

  • orbi_get_info -路由器型号、序列号、固件版本
  • orbi_get_attached_devices -列出所有连接的设备，包括IP、MAC、信号强度
  • orbi_get_traffic_meter -带宽使用统计数据（今天/每月）
  • orbi_block_device -按MAC地址阻止设备
  • orbi_allow_device -解锁以前被阻止的设备
  • orbi_check_firmware -检查可用的固件更新
  • orbi_get_guest_wifi_status -获取访客网络状态（2.4GHz/5GHz）
  • orbi_set_guest_wifi -启用/禁用访客WiFi网络
  • orbi_reboot -重新启动路由器（导致临时网络中断）

部署

Docker Compose（推荐）

docker compose up -d

取消突袭

  1. 将文件复制到 /mnt/user/appdata/homelab-mcp/
  2. 构建并运行：
docker build -t homelab-mcp .
docker run -d --name homelab-mcp \
  -p 6971:6971 \
  -v /mnt/user/appdata/homelab-mcp/config.yaml:/app/config.yaml:ro \
  homelab-mcp

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: homelab-mcp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: homelab-mcp
  template:
    metadata:
      labels:
        app: homelab-mcp
    spec:
      containers:
      - name: homelab-mcp
        image: homelab-mcp:latest
        ports:
        - containerPort: 6971
        volumeMounts:
        - name: config
          mountPath: /app/config.yaml
          subPath: config.yaml
      volumes:
      - name: config
        configMap:
          name: homelab-mcp-config

添加新服务

  1. 在下创建新目录 homelab_mcp/services/
  2. 实施 ServiceBase 类与：
    • _create_client() -HTTP客户端设置
    • register_tools() -MCP工具注册
    • health_check() -服务健康检查
  3. 将配置模型添加到 core/config.py
  4. 注册于 server.py

MCP客户端配置

添加到您的MCP客户端（例如Windsurf）：

{
  "mcpServers": {
    "homelab": {
      "serverType": "streamable-http",
      "url": "http://192.168.1.100:6971/mcp"
    }
  }
}

许可证

麻省理工学院

相关 MCP