Command Palette

Search for a command to run...

UnylyUnyly
Весь каталог

Homelab Infra

БесплатноНе проверен

Unified MCP server for homelab infrastructure — Nginx Proxy Manager, Docker, and DNS management

GitHubEmbed

Описание

Unified MCP server for homelab infrastructure — Nginx Proxy Manager, Docker, and DNS management

README

Made by Seaynic Labs. Need tools like this built around your own systems? We do that.

Homelab is an MCP server that lets an AI assistant manage Nginx Proxy Manager proxy hosts, Docker containers and Cloudflare DNS records from one place. It covers the path from a container to a public web address. One call, expose_service, checks the container, adds the DNS record and the proxy host, and shows the plan before anything changes. Four more optional modules cover Uptime Kuma, Cloudflare Tunnel, AdGuard Home and Authentik.

It is a bundle: one server made of modules, plus skills that teach the assistant the workflows. You switch on the modules you use. New modules arrive switched off, so an update never changes what your assistant can do until you choose to.

Audience: self-hosters running a homelab.

Module What it does Status
proxy Nginx Proxy Manager: proxy hosts, redirections, SSL certificates, access lists On by default
docker Containers, images and volumes through the local Docker socket or Portainer On by default
dns Cloudflare DNS zones and records, and BIND export On by default
home_assistant Entities, automations, scripts and system info in Home Assistant Off by default, turn on with HOMELAB_HOME_ASSISTANT_ENABLED=true
uptime Uptime Kuma monitors: list and read status (read only) Off by default, turn on with HOMELAB_UPTIME_ENABLED=true
tunnel Cloudflare Tunnel routes: list, add and remove Off by default, turn on with HOMELAB_TUNNEL_ENABLED=true
dns_filter AdGuard Home: filter status, query log and filter rules Off by default, turn on with HOMELAB_DNS_FILTER_ENABLED=true
sso Authentik: list applications, create a proxy provider and application for one host Off by default, turn on with HOMELAB_SSO_ENABLED=true

The core tools are always on: homelab_modules, homelab_health, expose_service, teardown_service, service_status, infrastructure_overview and diagnose_service.

Homelab works with any MCP client: Claude Desktop, Claude Code, Cursor, VS Code, Sonique, Hermes, OpenClaw and others. It runs on your own machine and keeps no data of its own. It talks only to the services you configure.

Install

Homelab needs Python 3.11 or newer. With uv there is nothing to install ahead of time. Pin the version so updates arrive only when you choose them:

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

Or with pip:

pip install homelab-infra-mcp==2.1.1

Upgrading from 2.0? Version 2.1 has no breaking changes. The four new modules are off by default. Read the 2.1.0 section of CHANGELOG.md.

Upgrading from 1.x? Version 2.0 changed the tool names and the environment variable names. Read the migration table in CHANGELOG.md first.

Quick install

Add the server to your MCP client (see Add it to your MCP client), set the variables for the modules you use, and restart the client. Then ask the assistant to call homelab_modules. The response lists each module, whether it is on, and which settings are missing.

Doctor

Run homelab-infra --doctor in a terminal before you start, and after any settings change:

homelab-infra --doctor

The doctor checks each enabled module's settings and reachability, the Docker socket access, and the TLS check. It prints a FIX line for each problem and exits with status 1 when something needs fixing.

Settings

Set these as environment variables in your MCP client's config, or put them in a config file (see below). You only need the settings for the modules you use. Homelab starts without any of them and tells you what is missing when you call a tool.

Variable Module What it is
HOMELAB_PROXY_URL proxy Nginx Proxy Manager address. Default http://localhost:81.
HOMELAB_PROXY_EMAIL / HOMELAB_PROXY_PASSWORD proxy The NPM admin login used for the API
HOMELAB_DOCKER_HOST docker Docker engine address. Default unix:///var/run/docker.sock.
HOMELAB_DOCKER_PORTAINER_URL / HOMELAB_DOCKER_PORTAINER_TOKEN docker Use Portainer instead of the socket. Both are needed.
HOMELAB_DOCKER_PORTAINER_ENDPOINT_ID docker Portainer endpoint id. Default 1.
HOMELAB_DNS_API_TOKEN dns Cloudflare API token with DNS edit permission on the zone
HOMELAB_DNS_ZONE_ID dns Default zone id, so tools can leave zone_id empty
HOMELAB_HOME_ASSISTANT_URL home_assistant Home Assistant address. Default http://homeassistant.local:8123.
HOMELAB_HOME_ASSISTANT_TOKEN home_assistant Long-lived access token
HOMELAB_UPTIME_URL uptime Uptime Kuma address
HOMELAB_UPTIME_API_KEY uptime Uptime Kuma API key. Read from /metrics, used for list and get.
HOMELAB_TUNNEL_API_TOKEN tunnel Cloudflare API token with tunnel edit permission
HOMELAB_TUNNEL_ACCOUNT_ID tunnel Cloudflare account id that owns the tunnel
HOMELAB_TUNNEL_TUNNEL_ID tunnel Cloudflare Tunnel id
HOMELAB_DNS_FILTER_URL dns_filter AdGuard Home address
HOMELAB_DNS_FILTER_USERNAME / HOMELAB_DNS_FILTER_PASSWORD dns_filter AdGuard Home login
HOMELAB_SSO_URL sso Authentik address
HOMELAB_SSO_TOKEN sso Authentik API token
HOMELAB_SSO_FLOW_SLUG sso Authorization flow slug that new proxy providers use
HOMELAB_<MODULE>_ENABLED any true or false. Turns a module on or off, e.g. HOMELAB_UPTIME_ENABLED=true.
HOMELAB_<MODULE>_ALLOW_WRITES any false by default: each change asks you first. true lets the assistant make changes in that module without asking. See Safety.
HOMELAB_READ_ONLY all true refuses every change, whatever else is set. Reads and dry runs still work.
HOMELAB_<MODULE>_<KEY>_FILE any Read a secret from a file instead, e.g. HOMELAB_DNS_API_TOKEN_FILE=/run/secrets/cf_token
HOMELAB_CONFIG core Path to the config file. Default ~/.config/homelab/config.toml.
HOMELAB_APPROVAL_LOG core Path to the approval log. Default ~/.local/state/homelab/approvals.jsonl, or $XDG_STATE_HOME/homelab/approvals.jsonl when XDG_STATE_HOME is set.

Config file (optional). Homelab also reads ~/.config/homelab/config.toml, or the file named by HOMELAB_CONFIG. Each module has its own table. Environment variables win over the file.

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

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

Turn a module on in the same file with its enabled key, or with HOMELAB_<MODULE>_ENABLED=true in the environment.

Add it to your MCP client

Most clients use the same JSON shape. Pin the version so the server runs the release you tested. Put the block where your client keeps MCP servers:

{
  "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"
      }
    }
  }
}
Client Where the config goes
Claude Desktop claude_desktop_config.json (Settings → Developer → Edit Config)
Claude Code claude mcp add homelab -- uvx homelab-infra-mcp==2.1.1, then add the env values, or a project .mcp.json
Cursor ~/.cursor/mcp.json, or .cursor/mcp.json in a project
VS Code .vscode/mcp.json, using "servers" instead of "mcpServers"
Sonique, Hermes, OpenClaw, others Any client that launches a stdio MCP server: command uvx, args ["homelab-infra-mcp==2.1.1"], plus the env values

As a Claude Code plugin. The plugin installs the server and the skills together. Its .mcp.json pins homelab-infra-mcp==2.1.1. Set the variables in your environment or in the config file.

Over HTTP. For clients that connect to a URL instead of launching a process:

homelab-infra --transport http --port 8200

It serves streamable HTTP at http://127.0.0.1:8200/mcp. It listens only on your own machine by default. Put authentication in front of it before exposing it anywhere else.

Tools

The default install has 16 tools. Each module adds its own tools when you turn it on.

Tool What it does
homelab_modules Which modules are on, which settings are missing, and what each tool does. Call this first.
homelab_health Connectivity and version for every enabled module
expose_service Check a container, add a DNS record (optional), add a proxy host. One approved plan.
teardown_service Remove a service's proxy host and optional DNS record. One approved plan.
service_status One view of a service: container, proxy hosts, DNS records
infrastructure_overview Counts across Docker, the proxy and DNS
diagnose_service Read only. Checks each hop from a domain to its service, one row per hop. Returns the first failing hop and its fix.
proxy_hosts list, get, create, update, delete proxy hosts
proxy_redirections list, create, delete HTTP redirections
proxy_certificates list, request a Let's Encrypt certificate
proxy_access_lists list, create, delete IP access lists
docker_containers list, get, start, stop, restart, remove, logs, stats, prune
docker_images list, pull, remove, prune
docker_inventory volumes, networks, or Portainer stacks (with a stack's compose file)
dns_zones list zones, or export one in BIND format
dns_records list, get, create, update, delete records
ha_entities list, get, search; call_service, turn_on, turn_off, toggle (Home Assistant)
ha_automations list, trigger, reload automations or scripts; create previews automation YAML (Home Assistant)
ha_system Config, available services, check_config (Home Assistant)
uptime_monitors list, get: read only (Uptime Kuma). Pause and resume are not in 2.1.
tunnel_routes list; add, remove need approval (Cloudflare Tunnel)
dns_filter_status Filter status and query and block totals (AdGuard Home, read only)
dns_filter_queries Paged query log (AdGuard Home, read only)
dns_filter_rules list blocked services and custom rules; add, remove need approval (AdGuard Home)
sso_applications list; create makes a proxy provider and an application for one host, and needs approval (Authentik)

Every tool returns structured data with a published schema, so an assistant can write code against the results. Lists take limit and offset. Every change tool takes dry_run=true, which shows exactly what would change and changes nothing. Errors always look like homelab.<module>.<code>: <message> Fix: <hint>.

Skills

Skills are short guides the assistant reads before a job. Homelab ships them in a skills/ folder for apps that read Agent Skills, and serves each one as an MCP prompt for every other client.

Written for Homelab

Skill What it covers
getting-started Which modules are on, the settings each needs, the first checks, how approvals work
expose-a-service-safely Put one container on a public name: dry run, approval, per-hop diagnosis, outside check
homelab-health-check A read-only sweep of modules, containers, certificates, monitors and DNS filtering
homelab-troubleshooting Root-cause investigation for a failing service, one hypothesis at a time
fix-and-deploy Verify a fix against the original symptom, deploy it, check the live target
containers Status, logs, restarts, stats and images for Docker containers
runbook An operational runbook for one service, with facts pulled from the live tools
diagram An editable draw.io file from a description
network-diagram A draw.io map of services, Docker networks, the proxy and the DNS path

Third-party, under their own licenses

Skill Author License
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

Each third-party skill keeps its license file. See CREDITS.md for the pinned upstream commits.

Try these

  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.

Safety

  • Read-only tools never change anything. The assistant can list, inspect, search and read logs freely. diagnose_service makes read-only calls only.
  • Every change needs your approval. When the assistant asks to change something, Homelab asks you directly through your MCP client (MCP elicitation) and shows the exact change: the domain, the target, the container, the DNS record. The assistant cannot answer for you. No argument it sets counts as approval.
  • Every decision is logged. Each approve, decline and refusal goes into a local approval log. The default path is ~/.local/state/homelab/approvals.jsonl. Set HOMELAB_APPROVAL_LOG to choose another path.
  • Dry runs show the plan. Every change tool accepts dry_run=true. It shows what would change and changes nothing.
  • Pre-approve only what you trust. HOMELAB_<MODULE>_ALLOW_WRITES=true lets the assistant make changes in that module without asking. Use it for modules you are happy to automate, and leave it off for the rest.
  • Some clients can't ask you questions. In those, a change returns approval_unavailable, and the message names the setting to pre-approve or the setting to leave alone.
  • Read-only mode. HOMELAB_READ_ONLY=true refuses all changes, even pre-approved ones.
  • Secrets stay out of responses. Tokens, passwords and keys come from the environment, a file, or the config file. homelab_modules reports whether a setting is set, never its value.
  • Docker socket access is root on the host. Mount the socket read-only when you only need to look, and use Portainer if you would rather not mount it at all.
  • Tunnel and SSO changes reach the public internet. Review each tunnel_routes and sso_applications plan before you approve it.
  • Homelab only calls the services you configure. It sends nothing anywhere else and keeps no data.

See SECURITY.md for the secrets list, the approval log and the reporting process.

Security card
Network Only the services you configure: your Nginx Proxy Manager, your Docker engine or Portainer, api.cloudflare.com (DNS and Tunnel), and the Uptime Kuma, AdGuard Home, Authentik and Home Assistant addresses you set. diagnose_service also opens TCP and TLS connections to your upstreams and public domains. No telemetry.
Files Reads its config file (/.config/homelab/config.toml). Writes one local approval log (/.local/state/homelab/approvals.jsonl), which never leaves the machine.
Secrets API keys, tokens and passwords come from your environment or config file. They are never tool arguments and never returned to the model.
Read-only tools 7: docker_inventory, dns_zones, service_status, infrastructure_overview, diagnose_service, homelab_modules, homelab_health
Needs your approval proxy_hosts, proxy_redirections, proxy_certificates, proxy_access_lists, docker_containers, docker_images, dns_records, expose_service, teardown_service: you approve each change in your app, or pre-approve a module in settings. The AI cannot approve for you.
Startup cost about 10,200 tokens (16 tools, 14 skill prompts)
Changes Tool descriptions are locked by hash (tool-manifest.lock.json); CI fails if they change silently.

Develop

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

The tests never touch a real network or Docker engine. HTTP goes through httpx.MockTransport, and the Docker client is a fake.

License

MIT. See LICENSE. Third-party skills keep their own licenses; see CREDITS.md.


Built by Seaynic Labs. We build tools like this around a business's own systems: local-first, with a person approving every change. See custom integrations.

from github.com/seayniclabs/homelab-infra-mcp

Установить Homelab Infra в Claude Desktop, Claude Code, Cursor

Рекомендуется · одна команда, все IDE
unyly install homelab-infra

Ставит в Claude Desktop, Claude Code, Cursor и VS Code — сам разбирается с npx, uvx и сборкой из исходников.

Впервые? Поставь CLI: curl -fsSL https://unyly.org/install | sh

Или настроить вручную

Выполни в терминале:

claude mcp add homelab-infra -- uvx homelab-infra-mcp

Пошаговые гайды: как установить Homelab Infra

FAQ

Homelab Infra MCP бесплатный?

Да, Homelab Infra MCP бесплатный — установка в пару кликов через Unyly без оплаты.

Нужен ли API-ключ для Homelab Infra?

Нет, Homelab Infra работает без API-ключей и переменных окружения.

Homelab Infra — hosted или self-hosted?

Self-hosted: сервер запускается локально на твоей машине командой из раздела установки.

Как установить Homelab Infra в Claude Desktop, Claude Code или Cursor?

Открой Homelab Infra на unyly.org, выбери вкладку своего клиента (Claude Desktop, Claude Code, Cursor) и нажми Install — конфиг сгенерируется автоматически, без правки JSON.

Похожие MCP

Compare Homelab Infra with

Не уверен что выбрать?

Найди свой стек за 60 секунд

Автор?

Embed-бейдж для README

Похожее

Все в категории development