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)每个适配器：
- 住在
homeops_mcp/adapters/_adapter.py - 实现通用接口(
BaseAdapter) - 未配置上游服务时返回模拟/演示数据
- 有自己的单元测试
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提示。
许可证
麻省理工学院——见 许可证.