homelab-infra-mcp

Homelab

Homelab 是一个 MCP 服务，可让 AI 助手在同一处管理 Nginx Proxy Manager 代理主机、Docker 容器和 Cloudflare DNS 记录。它覆盖了从容器到公开网址的整个流程。一次调用 expose_service，即可检查容器、添加 DNS 记录和代理主机，并在进行任何更改前显示计划。另有四个可选模块，分别支持 Uptime Kuma、Cloudflare Tunnel、AdGuard Home 和 Authentik。

它是一个套件：由多个模块组成的单个服务，以及用于向助手传授工作流的技能。你可以启用所需的模块。新模块默认关闭，因此更新不会改变助手的功能，除非你主动选择启用。

适用对象： 运行家庭实验室的自托管用户。

模块	功能	状态
proxy	Nginx Proxy Manager：代理主机、重定向、SSL 证书、访问列表	默认开启
docker	通过本地 Docker 套接字或 Portainer 管理容器、映像和卷	默认开启
dns	Cloudflare DNS 区域和记录，以及 BIND 导出	默认开启
home_assistant	Home Assistant 中的实体、自动化、脚本和系统信息	默认关闭，通过 HOMELAB_HOME_ASSISTANT_ENABLED=true 开启
uptime	Uptime Kuma 监视器：列出并读取状态（只读）	默认关闭，通过 HOMELAB_UPTIME_ENABLED=true 开启
tunnel	Cloudflare Tunnel 路由：列出、添加和移除	默认关闭，通过 HOMELAB_TUNNEL_ENABLED=true 开启
dns_filter	AdGuard Home：过滤状态、查询日志和过滤规则	默认关闭，通过 HOMELAB_DNS_FILTER_ENABLED=true 开启
sso	Authentik：列出应用，为单个主机创建代理提供程序和应用	默认关闭，通过 HOMELAB_SSO_ENABLED=true 开启

核心工具始终开启：homelab_modules、homelab_health、expose_service、teardown_service、service_status、infrastructure_overview 和 diagnose_service。

Homelab 适用于任何 MCP 客户端：Claude Desktop、Claude Code、Cursor、VS Code、Sonique、Hermes、OpenClaw 等。它运行在你自己的机器上，不会存储任何自身数据。它只与您配置的服务通信。

安装

Homelab 需要 Python 3.11 或更高版本。使用 uv 时，无需预先安装任何内容。固定版本，这样只有在你选择更新时才会收到更新：

uvx homelab-infra-mcp==2.1.1 --version

也可以使用 pip：

pip install homelab-infra-mcp==2.1.1

从 2.0 升级？2.1 版本没有破坏性变更。四个新模块默认关闭。请阅读 CHANGELOG.md 中的 2.1.0 部分。

从 1.x 升级？2.0 版本更改了工具名称和环境变量名称。请先阅读 CHANGELOG.md 中的迁移表。

快速安装

将服务添加到 MCP 客户端（请参阅添加到 MCP 客户端），为所需模块设置变量，然后重启客户端。接着让助手调用 homelab_modules。响应会列出各个模块、模块是否开启，以及缺少哪些设置。

Doctor

开始前以及每次更改设置后，在终端中运行 homelab-infra --doctor：

homelab-infra --doctor

Doctor 会检查每个已启用模块的设置和可访问性、Docker 套接字访问权限，以及 TLS 检查。每个问题都会打印一行 FIX，如果有问题需要修复，则以状态码 1 退出。

设置

在 MCP 客户端的配置中将这些设为环境变量，或将它们写入配置文件（见下文）。你只需要设置所用模块对应的变量。Homelab 无需任何设置即可启动，并会在你调用工具时告知缺少哪些设置。

变量	模块	说明
HOMELAB_PROXY_URL	proxy	Nginx Proxy Manager 地址。默认值为 http://localhost:81。
HOMELAB_PROXY_EMAIL / HOMELAB_PROXY_PASSWORD	proxy	用于 API 的 NPM 管理员登录凭据
HOMELAB_DOCKER_HOST	docker	Docker 引擎地址。默认值为 unix:///var/run/docker.sock。
HOMELAB_DOCKER_PORTAINER_URL / HOMELAB_DOCKER_PORTAINER_TOKEN	docker	使用 Portainer 代替套接字。两项都必须设置。
HOMELAB_DOCKER_PORTAINER_ENDPOINT_ID	docker	Portainer 端点 ID。默认值为 1。
HOMELAB_DNS_API_TOKEN	dns	拥有该区域 DNS 编辑权限的 Cloudflare API 令牌
HOMELAB_DNS_ZONE_ID	dns	默认区域 ID，因此工具可以将 zone_id 留空
HOMELAB_HOME_ASSISTANT_URL	home_assistant	Home Assistant 地址。默认值为 http://homeassistant.local:8123。
HOMELAB_HOME_ASSISTANT_TOKEN	home_assistant	长期访问令牌
HOMELAB_UPTIME_URL	uptime	Uptime Kuma 地址
HOMELAB_UPTIME_API_KEY	uptime	Uptime Kuma API 密钥。从 /metrics 读取，用于 list 和 get。
HOMELAB_TUNNEL_API_TOKEN	tunnel	拥有隧道编辑权限的 Cloudflare API 令牌
HOMELAB_TUNNEL_ACCOUNT_ID	tunnel	拥有该隧道的 Cloudflare 账户 ID
HOMELAB_TUNNEL_TUNNEL_ID	tunnel	Cloudflare Tunnel ID
HOMELAB_DNS_FILTER_URL	dns_filter	AdGuard Home 地址
HOMELAB_DNS_FILTER_USERNAME / HOMELAB_DNS_FILTER_PASSWORD	dns_filter	AdGuard Home 登录凭据
HOMELAB_SSO_URL	sso	Authentik 地址
HOMELAB_SSO_TOKEN	sso	Authentik API 令牌
HOMELAB_SSO_FLOW_SLUG	sso	新代理提供程序使用的授权流程 slug
HOMELAB_<MODULE>_ENABLED	任意	true 或 false。用于启用或停用模块，例如 HOMELAB_UPTIME_ENABLED=true。
HOMELAB_<MODULE>_ALLOW_WRITES	任意	默认值为 false：每次更改都需要先征求你的同意。设为 true 后，助手可在该模块中直接进行更改，无需征求同意。参见 安全性。
HOMELAB_READ_ONLY	全部	设为 true 时，无论其他设置如何，都会拒绝所有更改。读取和试运行仍可进行。
HOMELAB_<MODULE>_<KEY>_FILE	任意	改为从文件中读取机密，例如 HOMELAB_DNS_API_TOKEN_FILE=/run/secrets/cf_token
HOMELAB_CONFIG	核心	配置文件路径。默认值为 ~/.config/homelab/config.toml。
HOMELAB_APPROVAL_LOG	核心	审批日志路径。默认值为 ~/.local/state/homelab/approvals.jsonl；若设置了 XDG_STATE_HOME，则为 $XDG_STATE_HOME/homelab/approvals.jsonl。

配置文件（可选）。 Homelab 也会读取 ~/.config/homelab/config.toml，或 HOMELAB_CONFIG 指定的文件。每个模块都有自己的表。环境变量优先于文件中的设置。

[proxy]
email = "[email protected]"
password = "change-me"

[dns]
api_token = "your-cloudflare-token"
zone_id = "your-zone-id"

在同一文件中通过模块的 enabled 键启用该模块，或在环境变量中设置 HOMELAB_<MODULE>_ENABLED=true。

添加到 MCP 客户端

大多数客户端使用相同的 JSON 结构。固定版本，确保服务运行的是你测试过的版本。将此代码块放在客户端保存 MCP 服务配置的位置：

{
  "mcpServers": {
    "homelab": {
      "command": "uvx",
      "args": ["homelab-infra-mcp==2.1.1"],
      "env": {
        "HOMELAB_PROXY_EMAIL": "[email protected]",
        "HOMELAB_PROXY_PASSWORD": "change-me",
        "HOMELAB_DNS_API_TOKEN": "your-cloudflare-token",
        "HOMELAB_DNS_ZONE_ID": "your-zone-id"
      }
    }
  }
}

客户端	配置位置
Claude Desktop	claude_desktop_config.json（Settings → Developer → Edit Config）
Claude Code	claude mcp add homelab -- uvx homelab-infra-mcp==2.1.1，然后添加 env 值，或使用项目的 .mcp.json
Cursor	~/.cursor/mcp.json，或项目中的 .cursor/mcp.json
VS Code	.vscode/mcp.json，使用 "servers" 而不是 "mcpServers"
Sonique、Hermes、OpenClaw 等	任何可启动 stdio MCP 服务的客户端：命令为 uvx，参数为 ["homelab-infra-mcp==2.1.1"]，另加 env 值

作为 Claude Code 插件。 该插件会一并安装服务和技能。其 .mcp.json 固定使用 homelab-infra-mcp==2.1.1。在环境变量或配置文件中设置这些变量。

通过 HTTP 连接。 对于连接 URL 而不是启动进程的客户端：

homelab-infra --transport http --port 8200

它会在 http://127.0.0.1:8200/mcp 提供可流式传输的 HTTP 服务。默认情况下，它只监听本机。在其他任何地方公开之前，请先在它前面设置身份验证。

工具

默认安装包含 16 个工具。启用各个模块后，每个模块都会添加自己的工具。

工具	功能
homelab_modules	查看已启用的模块、缺少的设置，以及每个工具的功能。请先调用此工具。
homelab_health	检查每个已启用模块的连接状态和版本
expose_service	检查容器、添加 DNS 记录（可选）、添加代理主机。生成一个经批准的计划。
teardown_service	移除服务的代理主机和可选的 DNS 记录。生成一个经批准的计划。
service_status	在一个视图中查看服务的容器、代理主机和 DNS 记录
infrastructure_overview	汇总 Docker、代理和 DNS 的数量
diagnose_service	只读。逐跳检查从域名到服务的链路，每跳一行。返回首个故障跳及其修复方法。
proxy_hosts	对代理主机执行 list、get、create、update、delete
proxy_redirections	对 HTTP 重定向执行 list、create、delete
proxy_certificates	list 证书，或申请 Let's Encrypt 证书
proxy_access_lists	对 IP 访问列表执行 list、create、delete
docker_containers	对容器执行 list、get、start、stop、restart、remove、logs、stats、prune
docker_images	对镜像执行 list、pull、remove、prune
docker_inventory	查看 volumes、networks，或 Portainer stacks（含堆栈的 compose 文件）
dns_zones	list 区域，或以 BIND 格式 export 一个区域
dns_records	对记录执行 list、get、create、update、delete
ha_entities	执行 list、get、search；执行 call_service、turn_on、turn_off、toggle（Home Assistant）
ha_automations	对自动化或脚本执行 list、trigger、reload；create 会预览自动化 YAML（Home Assistant）
ha_system	配置、可用服务、check_config（Home Assistant）
uptime_monitors	执行 list、get：只读（Uptime Kuma）。2.1 版不支持暂停和恢复。
tunnel_routes	执行 list；add、remove 需要批准（Cloudflare Tunnel）
dns_filter_status	过滤状态、查询总数和拦截总数（AdGuard Home，只读）
dns_filter_queries	分页查询日志（AdGuard Home，只读）
dns_filter_rules	list 被拦截的服务和自定义规则；add、remove 需要批准（AdGuard Home）
sso_applications	执行 list；create 会为一个主机创建代理提供方和应用，并需要批准（Authentik）

每个工具都会返回具有公开架构的结构化数据，助手可以据此编写代码。列表支持 limit 和 offset。每个变更工具都支持 dry_run=true，可准确显示将要发生的变更，但不会实际进行任何更改。错误始终采用 homelab.<module>.<code>: <message> Fix: <hint> 格式。

技能

技能是助手在执行任务前阅读的简短指南。Homelab 会将它们放在 skills/ 文件夹中，供读取 Agent Skills 的应用使用，并将每项技能作为 MCP 提示词提供给其他所有客户端。

为 Homelab 编写

技能	涵盖内容
getting-started	哪些模块已启用、每个模块需要哪些设置、初始检查、审批的工作方式
expose-a-service-safely	使用公开名称发布一个容器：试运行、审批、逐跳诊断、外部检查
homelab-health-check	只读检查模块、容器、证书、监控项和 DNS 过滤
homelab-troubleshooting	针对故障服务进行根因排查，每次验证一个假设
fix-and-deploy	根据原始症状验证修复、部署修复、检查线上目标
containers	Docker 容器的状态、日志、重启、统计信息和镜像
runbook	针对单项服务的运维手册，信息取自实时工具
diagram	根据描述生成可编辑的 draw.io 文件
network-diagram	展示服务、Docker 网络、代理和 DNS 路径的 draw.io 图

第三方技能，遵循各自的许可证

技能	作者	许可证
systematic-debugging	Jesse Vincent，obra/superpowers	MIT
cloudflare、cloudflare-one	Cloudflare，cloudflare/skills	Apache-2.0
dashmotion	csthink，csthink/dashmotion	MIT
architecture-diagram	Cocoon-AI，architecture-diagram-generator	MIT

每项第三方技能都保留其许可证文件。固定的上游提交请参阅 CREDITS.md。

试试这些

1. Call homelab_modules and tell me which modules are on and which settings are missing.
2. Show every container that is restarting or unhealthy, with its last ten log lines.
3. Dry-run expose_service for wiki-app on wiki.example.com, port 8080, and show me the plan.
4. Diagnose wiki.example.com and fix the first failing hop.
5. Run the homelab health check and give me one table.

安全

• 只读工具绝不会更改任何内容。 助手可以自由列出、检查、搜索和读取日志。diagnose_service 只会进行只读调用。
• 每项更改都需要你的批准。 助手请求更改内容时，Homelab 会通过你的 MCP 客户端（MCP elicitation）直接向你确认，并显示具体更改：域名、目标、容器、DNS 记录。助手无法代替你作答。它设置的任何参数都不算批准。
• 每项决定都会记录。 每次批准、拒绝和驳回都会写入本地批准日志。默认路径为 ~/.local/state/homelab/approvals.jsonl。设置 HOMELAB_APPROVAL_LOG 可选择其他路径。
• 试运行会显示计划。 每个更改工具都接受 dry_run=true。它会显示将要进行的更改，但不会实际更改任何内容。
• 只预先批准你信任的操作。 HOMELAB_<MODULE>_ALLOW_WRITES=true 可让助手在相应模块中无需询问即可进行更改。对你愿意自动化的模块启用此设置，其余模块则保持关闭。
• 有些客户端无法向你提问。 在这类客户端中，更改操作会返回 approval_unavailable，并在消息中指出应预先批准或保持原样的设置。
• 只读模式。 HOMELAB_READ_ONLY=true 会拒绝所有更改，即使这些更改已预先批准。
• 响应中不会泄露机密。 令牌、密码和密钥来自环境、文件或配置文件。homelab_modules 只会报告某项设置是否已设置，不会返回其值。
• 访问 Docker 套接字相当于获得主机上的 root 权限。 只需查看时，请以只读方式挂载套接字；如果你不想挂载套接字，则可使用 Portainer。
• 隧道和 SSO 更改会影响公共互联网。 批准前，请检查每项 tunnel_routes 和 sso_applications 计划。
• Homelab 只会调用你配置的服务。它不会向其他地方发送任何内容，也不会保留任何数据。

有关机密列表、批准日志和报告流程，请参阅 SECURITY.md。

安全卡片
网络	仅连接你配置的服务：你的 Nginx Proxy Manager、Docker 引擎或 Portainer、api.cloudflare.com（DNS 和 Tunnel），以及你设置的 Uptime Kuma、AdGuard Home、Authentik 和 Home Assistant 地址。diagnose_service 还会向你的上游服务和公共域名建立 TCP 和 TLS 连接。无遥测。
文件	读取其配置文件（/.config/homelab/config.toml）。写入一份本地批准日志（/.local/state/homelab/approvals.jsonl），该日志绝不会离开本机。
机密	API 密钥、令牌和密码来自你的环境或配置文件。它们绝不会作为工具参数，也绝不会返回给模型。
只读工具	7 个：docker_inventory、dns_zones、service_status、infrastructure_overview、diagnose_service、homelab_modules、homelab_health
需要你的批准	proxy_hosts、proxy_redirections、proxy_certificates、proxy_access_lists、docker_containers、docker_images、dns_records、expose_service、teardown_service：你需要在应用中批准每项更改，或在设置中预先批准相应模块。AI 无法代替你批准。
启动开销	约 10,200 个令牌（16 个工具，14 个技能提示词）
更改	工具说明通过哈希锁定（tool-manifest.lock.json）；如果说明被静默更改，CI 将失败。

开发

uv venv -p 3.11 .venv && uv pip install -e '.[dev]'
.venv/bin/pytest -q
python3 scripts/scan_identifiers.py --patterns <file> .

测试绝不会访问真实网络或 Docker 引擎。HTTP 请求通过 httpx.MockTransport 发送，Docker 客户端则使用模拟对象。

许可证

MIT。请参阅 LICENSE。第三方技能保留各自的许可证；请参阅 CREDITS.md。

---

由 Seaynic Labs 制作

发布者	Seaynic Labs
源代码	github.com/seayniclabs/homelab-infra-mcp
报告漏洞	GitHub 私密漏洞报告（请参阅 SECURITY.md）
致谢	CREDITS.md