AI导哈

模型上下文协议服务器

Homelab MCP Server是一个统一的模型上下文协议（MCP）服务器，用于将AI代理连接到自托管的家用实验室基础设施，提供多种服务和工具。

  • by theonlytruebigmac
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 theonlytruebigmac/homelab-mcp

使用说明

🏠 Homelab MCP Server

A unified Model Context Protocol (MCP) server that connects AI agents to your self-hosted homelab infrastructure.

暴露 9家庭实验室服务 通过人工智能助手的单一MCP端点（Claude、Gemini、ChatGPT、Cursor等）和自动化工具的完整REST API n8n.

✨ 特性

  • 30个整合的MCP工具 –基于动作的复合工具，保持上下文窗口的效率
  • MCP资源 –代理可以订阅的实时数据馈送（客户端、设备、队列、运行状况）
  • MCP提示 –用于常见任务（故障排除、安全审计、健康检查）的预构建提示模板
  • 完整REST API –每个工具也都通过Swagger文档作为REST端点公开
  • 有条件登记 –仅启用的服务注册其工具，保持工具列表干净
  • Docker首次部署 –单身 docker compose up 管理一切
  • 结构化错误处理 –具有正确HTTP状态代码的一致JSON错误
  • 审核日志记录 –每个工具调用都会被跟踪和记录

📦 支持服务列表

服务 类别 MCP工具 功能
优飞 网络 9 客户端、设备、防火墙、VLAN、安全、访客访问、备份
Proxmox 虚拟化 3 虚拟机、容器、快照、存储、电源管理
丛 媒体服务器 2 播放活动、库搜索、扫描、流控制
雷达/声纳 媒体管理 4 电影和电视搜索、添加内容、日历、下载队列
SABnzbd 下载 2 队列管理、速度限制、历史记录
波特纳 Docker 4 跨环境的容器、堆栈、卷、日志
OPNsense 防火墙 2 接口、DHCP、网关、固件、服务管理
家庭助手 物联网/智能家居 3 实体、自动化、场景、服务呼叫、历史
交通 反向代理 1 路由器检查、服务后端、运行状况概述

🚀 快速开始

先决条件

  • 码头工人 和 Docker Compose （推荐）
  • 或 Python 3.11+ 促进地方发展

1.克隆存储库

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

2.配置您的环境

cp .env.example .env

编辑 .env 并配置要使用的服务。每个服务都有一个 *_ENABLED flag--将任何服务设置为 false 要完全禁用它（它的工具和路由将不会被注册）：

# ---- MCP Server ----
MCP_HOST=0.0.0.0
MCP_PORT=3333

# ---- Logging ----
LOG_LEVEL=INFO            # DEBUG, INFO, WARNING, ERROR
LOG_JSON_FORMAT=false     # true for structured JSON logs

# ---- Unifi Controller ----
UNIFI_ENABLED=true
UNIFI_URL=https://192.168.1.1:8443
UNIFI_USERNAME=admin
UNIFI_PASSWORD=your_password_here
UNIFI_SITE=default
UNIFI_VERIFY_SSL=false

# ---- Radarr (Movies) ----
RADARR_ENABLED=true
RADARR_URL=http://your-radarr-ip:7878
RADARR_API_KEY=your_radarr_api_key_here

# ---- Sonarr (TV) ----
SONARR_ENABLED=true
SONARR_URL=http://your-sonarr-ip:8989
SONARR_API_KEY=your_sonarr_api_key_here

# ---- Plex ----
PLEX_ENABLED=true
PLEX_URL=http://your-plex-ip:32400
PLEX_TOKEN=your_plex_token_here

# ---- Proxmox ----
PROXMOX_ENABLED=true
PROXMOX_URL=https://your-proxmox-ip:8006
PROXMOX_USER=root@pam
PROXMOX_PASSWORD=your_password_here

# ---- Portainer ----
PORTAINER_ENABLED=true
PORTAINER_URL=http://your-portainer-ip:9000
PORTAINER_ACCESS_TOKEN=your_access_token_here

# ---- OPNsense ----
OPNSENSE_ENABLED=true
OPNSENSE_URL=https://your-opnsense-ip
OPNSENSE_API_KEY=your_api_key
OPNSENSE_API_SECRET=your_api_secret

# ---- Home Assistant ----
HASS_ENABLED=true
HASS_URL=http://homeassistant.local:8123
HASS_TOKEN=your_long_lived_access_token

# ---- SABnzbd ----
SABNZBD_ENABLED=true
SABNZBD_URL=http://localhost:8080
SABNZBD_API_KEY=your_api_key

# ---- Traefik ----
TRAEFIK_ENABLED=true
TRAEFIK_URL=http://localhost:8080
TRAEFIK_USERNAME=            # optional basic auth
TRAEFIK_PASSWORD=

提示： 您只需要配置实际使用的服务。集 *_ENABLED=false 对于其他所有工具，这些工具甚至不会出现在MCP工具列表中。

3.使用Docker Compose进行部署

docker compose up -d --build

服务器将在以下位置可用：

端点 URL 描述
主控程序 http://localhost:3333/mcp 在此处连接您的AI代理
REST API文档 http://localhost:3333/docs 交互式Swagger用户界面
健康检查 http://localhost:3333/health 服务器状态+版本
统一状态 http://localhost:3333/api/status 所有服务的健康

4.连接您的AI代理

Claude桌面/光标/Gemini CLI --添加到您的MCP配置中：

{
  "mcpServers": {
    "homelab-mcp": {
      "url": "http://<your-server-ip>:3333/mcp"
    }
  }
}

🛠️ 本地开发（无Docker）

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install the package in development mode
pip install -e ".[dev]"

# Configure environment
cp .env.example .env
# Edit .env with your service credentials

# Run the server
homelab-mcp

这 homelab-mcp 入口点定义见 pyproject.toml 并奔跑 src/homelab_mcp/server.py:main().

🏗️ 建筑

src/homelab_mcp/
├── server.py            # FastMCP + FastAPI app, tool/router registration, lifespan
├── config.py            # Pydantic Settings for all services
├── services/
│   ├── unifi/           # Unifi Controller integration
│   │   ├── client.py    # API client (aiohttp)
│   │   └── tools.py     # MCP tools + impl functions
│   ├── proxmox/         # Proxmox VE integration
│   ├── plex/            # Plex Media Server
│   ├── media/           # Radarr + Sonarr
│   ├── portainer/       # Docker via Portainer
│   ├── opnsense/        # OPNsense firewall
│   ├── hass/            # Home Assistant
│   ├── sabnzbd/         # SABnzbd Usenet
│   └── traefik/         # Traefik reverse proxy
├── routers/             # FastAPI REST routers (one per service)
└── utils/
    ├── logging.py       # @traced decorator, audit trail
    └── exceptions.py    # Structured error hierarchy

每个服务都遵循相同的模式：

  1. client.py -异步API客户端使用 aiohttp 采用延迟初始化
  2. tools.py — _impl MCP工具和REST路由器共享的功能，以及 register_*_tools() 注册整合的MCP工具、资源和提示

📡 n8n集成

此服务器提供了一个REST API，设计用于 n8n 工作流自动化：

  1. AI代理节点 --使用内置的MCP工具支持或“呼叫工作流”模式
  2. HTTP请求节点 --直接调用任何REST端点（请参阅Swagger /docs)
  3. 子工作流程 --将工具调用路由到REST端点，以实现复杂的自动化链

📚 文档

文档 描述
MCP工具参考 AI代理可用的所有工具
REST API参考 自动化的完整端点列表
Swagger用户界面 交互式API资源管理器（运行时）

📄 许可证

该项目根据 MIT许可证.

相关 MCP