AI导哈

家庭基础设施管理服务器

HomeOps MCP Server是一个为家庭基础设施管理设计的统一API服务器，支持Docker、Emby及未来Servarr/UniFi/CrowdSec集成，基于FastAPI和Python 3.11构建，适用于家庭实验室自动化。

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

使用说明

HomeOps MCP服务器

注： 该项目是由人工智能开发的，并完全由人工智能支持。没有人工支持——问题和PR由人工智能代理进行分类和响应。如果人工智能辅助软件不适合你，没有什么不好的感觉，但你可能需要重新考虑，因为你已经使用的大多数软件也是如此。

用于家庭基础设施管理的模型上下文协议（MCP）服务器。为Docker、Emby和未来的Servarr/UniFi/CowdSec集成提供统一的API。使用FastAPI和Python 3.11构建，用于Claude的家庭实验室自动化。

路线图

阶段 范围 状态
阶段0 骨架——项目结构、CI、Docker构建、健康端点 完成
第一阶段 Docker+Emby适配器、API-key身份验证中间件、完整CI管道 已计划
第2阶段 Servarr（Sonarr/Radarr/Prowlarr）、WordPress、Synology、UniFi、CrowdSec适配器 计划中
第三期 UI仪表板、审计日志、机密管理（Vault/SOPS）、生产强化 已计划

快速开始

选项A——Docker Compose（推荐）

cp .env.example .env
# Edit .env with your real values
docker compose up -d

服务器将在以下时间可用 http://localhost:8000.

选项B——在本地运行

# Requires Python 3.11+ and Poetry
poetry install
bash scripts/run_local.sh

配置

所有配置都是通过环境变量进行的。复制 .env.example 到 .env 并根据需要进行编辑。

变量 必填 默认 描述
MCP_ADMIN_KEY 是的 changeme-to-a-strong-random-key 管理终结点的API密钥
LOG_LEVEL 没有 INFO 日志记录级别(DEBUG, INFO, WARNING, ERROR)
EMBY_URL 没有 （模拟数据） Emby服务器URL，例如。 http://192.168.1.100:8096
EMBY_API_KEY 没有 （模拟数据） 用于身份验证的Emby API密钥
DOCKER_SOCKET 没有 unix:///var/run/docker.sock Docker套接字路径

API终点

方法 路径 身份验证 描述
GET /health 否 健康检查--返回 {"status": "ok"}
GET /v1/docker/containers API密钥 列出Docker容器
GET /v1/docker/containers/{id}/stats API密钥 容器资源统计信息
GET /v1/emby/sessions API密钥 列出活动的Emby会话
GET /v1/emby/search?q=term API密钥 搜索Emby库
POST /v1/actions/execute API密钥 日志操作（非破坏性）

所有经过身份验证的端点都需要 X-API-Key 标头设置为的值 MCP_ADMIN_KEY.

安全

  • 永远不要提交真正的API密钥或机密。 这 .env 文件被git忽略。
  • 中仅显示占位符值 .env.example.
  • Docker套接字以只读方式挂载在 docker-compose.yml.
  • 容器以非root用户身份运行(appuser).
  • 所有适配器API密钥都是在启动时从环境变量加载的，并且从不记录。

建筑

HomeOps MCP使用 适配器模式 与外部服务整合：

Client Request
      |
      v
  FastAPI Router
      |
      v
  Auth Middleware  (validates X-API-Key)
      |
      v
  Adapter Layer
      |
      +---> DockerAdapter    --> Docker Engine API (socket)
      +---> EmbyAdapter      --> Emby REST API
      +---> ServarrAdapter   --> Sonarr / Radarr / Prowlarr APIs  (Phase 2)
      +---> UniFiAdapter     --> UniFi Controller API              (Phase 2)
      +---> CrowdSecAdapter  --> CrowdSec LAPI                    (Phase 2)

每个适配器：

  1. 住在 homeops_mcp/adapters/<name>_adapter.py
  2. 实现通用接口(BaseAdapter)
  3. 未配置上游服务时返回模拟/演示数据
  4. 有自己的单元测试 tests/

发展

# Install all dependencies (including dev)
poetry install

# Run linter
poetry run ruff check .

# Run tests
poetry run pytest -v

# Build Docker image
docker build -t homeops-mcp .

贡献

此回购中的每个问题都是 AI就绪 --具有完整的上下文、文件路径、实现指南和即用型AI提示。

浏览问题→

许可证

麻省理工学院——见 许可证.

相关 MCP