Homelab
Homelab is an MCP server for managing homelab infrastructure with approval-gated changes and read-only diagnostics.
Inspect module status/health and missing settings (
homelab_modules,homelab_health).Manage Nginx Proxy Manager proxy hosts, HTTP redirections, SSL certificates, and IP access lists.
Manage Docker containers, images, volumes/networks/Portainer stacks, including logs/stats and start/stop/restart/remove/prune.
Manage Cloudflare DNS zones/records and export zone data in BIND format.
Expose or tear down services end-to-end (container check, optional DNS CNAME, NPM proxy host) with dry-run plans.
Get service status, infrastructure overview, and per-hop diagnosis from domain to upstream container.
Enable optional modules for Home Assistant, Uptime Kuma, Cloudflare Tunnel, AdGuard Home, and Authentik.
Use dry runs, approval prompts, approval logging, pre-approval settings, and read-only mode for safe operation.
Manages Cloudflare DNS: list zones, export a zone in BIND format, and list, get, create, update and delete DNS records, e.g. adding the CNAME needed to expose a homelab service.
Controls Docker engines over the local socket or a remote host: lists, inspects, starts, stops, restarts and removes containers, reads logs and stats, pulls, removes and prunes images, and manages volumes and networks.
Optional module for Home Assistant: list, get and search entities, call services or turn entities on/off/toggle, list, trigger and reload automations and scripts, preview new automation YAML, and read system config and check configuration.
Manages Nginx Proxy Manager instances: list, inspect, create, update and delete proxy hosts, HTTP redirections, IP access lists, and request Let's Encrypt SSL certificates, all via the NPM API.
Uses Portainer as an alternative to the Docker socket for container operations, including listing Portainer stacks and reading their compose files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Homelab expose my jellyfin container at jellyfin.example.com with SSL"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Homelab
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 |
| Nginx Proxy Manager: proxy hosts, redirections, SSL certificates, access lists | On by default |
| Containers, images and volumes through the local Docker socket or Portainer | On by default |
| Cloudflare DNS zones and records, and BIND export | On by default |
| Entities, automations, scripts and system info in Home Assistant | Off by default, turn on with |
| Uptime Kuma monitors: list and read status (read only) | Off by default, turn on with |
| Cloudflare Tunnel routes: list, add and remove | Off by default, turn on with |
| AdGuard Home: filter status, query log and filter rules | Off by default, turn on with |
| Authentik: list applications, create a proxy provider and application for one host | Off by default, turn on with |
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 --versionOr with pip:
pip install homelab-infra-mcp==2.1.1Upgrading 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 --doctorThe 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.
Related MCP server: npm-mcp
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 |
| proxy | Nginx Proxy Manager address. Default |
| proxy | The NPM admin login used for the API |
| docker | Docker engine address. Default |
| docker | Use Portainer instead of the socket. Both are needed. |
| docker | Portainer endpoint id. Default |
| dns | Cloudflare API token with DNS edit permission on the zone |
| dns | Default zone id, so tools can leave |
| home_assistant | Home Assistant address. Default |
| home_assistant | Long-lived access token |
| uptime | Uptime Kuma address |
| uptime | Uptime Kuma API key. Read from |
| tunnel | Cloudflare API token with tunnel edit permission |
| tunnel | Cloudflare account id that owns the tunnel |
| tunnel | Cloudflare Tunnel id |
| dns_filter | AdGuard Home address |
| dns_filter | AdGuard Home login |
| sso | Authentik address |
| sso | Authentik API token |
| sso | Authorization flow slug that new proxy providers use |
| any |
|
| any |
|
| all |
|
| any | Read a secret from a file instead, e.g. |
| core | Path to the config file. Default |
| core | Path to the approval log. Default |
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 = "admin@example.com"
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": "admin@example.com",
"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 Code |
|
Cursor |
|
VS Code |
|
Sonique, Hermes, OpenClaw, others | Any client that launches a stdio MCP server: command |
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 8200It 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 |
| Which modules are on, which settings are missing, and what each tool does. Call this first. |
| Connectivity and version for every enabled module |
| Check a container, add a DNS record (optional), add a proxy host. One approved plan. |
| Remove a service's proxy host and optional DNS record. One approved plan. |
| One view of a service: container, proxy hosts, DNS records |
| Counts across Docker, the proxy and DNS |
| Read only. Checks each hop from a domain to its service, one row per hop. Returns the first failing hop and its fix. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Config, available services, |
|
|
|
|
| Filter status and query and block totals (AdGuard Home, read only) |
| Paged query log (AdGuard Home, read only) |
|
|
|
|
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 |
| Which modules are on, the settings each needs, the first checks, how approvals work |
| Put one container on a public name: dry run, approval, per-hop diagnosis, outside check |
| A read-only sweep of modules, containers, certificates, monitors and DNS filtering |
| Root-cause investigation for a failing service, one hypothesis at a time |
| Verify a fix against the original symptom, deploy it, check the live target |
| Status, logs, restarts, stats and images for Docker containers |
| An operational runbook for one service, with facts pulled from the live tools |
| An editable draw.io file from a description |
| A draw.io map of services, Docker networks, the proxy and the DNS path |
Third-party, under their own licenses
Skill | Author | License |
| Jesse Vincent, obra/superpowers | MIT |
| Cloudflare, cloudflare/skills | Apache-2.0 |
| csthink, csthink/dashmotion | MIT |
| Cocoon-AI, architecture-diagram-generator | MIT |
Each third-party skill keeps its license file. See CREDITS.md for the pinned upstream commits.
Try these
Call homelab_modules and tell me which modules are on and which settings are missing.Show every container that is restarting or unhealthy, with its last ten log lines.Dry-run expose_service for wiki-app on wiki.example.com, port 8080, and show me the plan.Diagnose wiki.example.com and fix the first failing hop.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_servicemakes 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. SetHOMELAB_APPROVAL_LOGto 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=truelets 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=truerefuses 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_modulesreports 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_routesandsso_applicationsplan 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 ( |
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: |
Needs your approval |
|
Startup cost | about 10,200 tokens (16 tools, 14 skill prompts) |
Changes | Tool descriptions are locked by hash ( |
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.
Available Tools
16 toolsdiagnose_serviceARead-only
Check each hop between a public domain and its upstream container, and name the first one that fails with the fix for it. Hops: DNS record, tunnel route (if the tunnel module is on), Nginx Proxy Manager host, TLS certificate (expiry and trust), upstream container running (Docker), upstream port answering, uptime monitor (if on), Authentik login in front (if on). Read-only: it changes nothing.
Inputs: domain (required). Returns: hops, note, domain, first_failure
dns_recordsADestructive
DNS records. list and get are read-only. create, update and delete change the zone and need the person's approval (or HOMELAB_DNS_ALLOW_WRITES=true). create needs name, record_type and content; update needs record_id and any field to change; delete removes the record permanently.
Inputs: ttl, name, page, limit, +7 more. Returns: page, items, change, detail, +1 more
dns_zonesBRead-only
Zones for the Cloudflare account (action=list), or one zone exported in BIND format (action=export).
Inputs: page, limit, action, zone_id. Returns: page, zones, action, export, +2 more
docker_containersADestructive
Containers. list, get, logs and stats are read-only. start, stop, restart, remove and prune change state and need the person's approval (or HOMELAB_DOCKER_ALLOW_WRITES=true). remove deletes a container permanently. prune removes ALL stopped containers. container is a name or id (not needed for list or prune).
Inputs: all, tail, limit, since, +5 more. Returns: logs, items, stats, total, +3 more
docker_imagesADestructive
Images. list is read-only. pull, remove and prune change the host and need approval (or HOMELAB_DOCKER_ALLOW_WRITES=true). remove deletes an image; prune removes dangling and unused images.
Inputs: tag, force, image, limit, +3 more. Returns: items, total, change, has_more
docker_inventoryARead-only
Read-only lists: volumes, networks, or Portainer stacks (stacks need the Portainer backend). Pass stack_id with kind=stacks to get that stack's compose file.
Inputs: kind, limit, offset, stack_id. Returns: kind, items, total, backend, +2 more
expose_serviceADestructive
Expose a container: check it runs, add a Cloudflare CNAME to tunnel_hostname (only if given), and add an Nginx Proxy Manager host that forwards domain to forward_host:forward_port. The plan is shown to the person before anything changes.
Inputs: domain (required), forward_port (required), container_name (required), dry_run, +3 more. Returns: note, errors, dry_run, planned, +3 more
homelab_healthARead-only
Connectivity and version for every enabled module. A module with missing settings reports the variable it needs.
Inputs: no named parameters. Returns: modules, version
homelab_modulesARead-only
Which modules are on, which settings are missing, whether writes are pre-approved, and what each tool does. Pass a module name for its full settings list (values are never shown, only whether they are set).
Inputs: module. Returns: skills, modules, version, homepage, +4 more
infrastructure_overviewARead-only
Counts across Docker, Nginx Proxy Manager and Cloudflare DNS, in one call.
Inputs: no named parameters. Returns: dns, proxy, docker
proxy_access_listsADestructive
IP access lists. list is read-only. create and delete need approval (or ALLOW_WRITES). allow and deny are comma-separated IPs or CIDRs. Deleting a list affects every proxy host that uses it.
Inputs: deny, name, allow, limit, +4 more. Returns: items, total, change, has_more
proxy_certificatesADestructive
SSL certificates. list is read-only. request asks Let's Encrypt for a new certificate (needs approval, or ALLOW_WRITES). Let's Encrypt must be able to reach the domains.
Inputs: limit, action, offset, dry_run, +1 more. Returns: items, total, change, has_more
proxy_hostsADestructive
Proxy hosts. list/get are read-only. create, update and delete change NPM and need the person's approval (or HOMELAB_PROXY_ALLOW_WRITES=true). dry_run=true previews without asking.
Inputs: ssl, limit, action, offset, +7 more. Returns: items, total, change, detail, +1 more
proxy_redirectionsCDestructive
HTTP redirections. list is read-only; create and delete need approval (or ALLOW_WRITES).
Inputs: limit, action, offset, dry_run, +5 more. Returns: items, total, change, has_more
service_statusCRead-only
One view of a service: the container, the proxy hosts that name the domain, and its DNS records.
Inputs: container_name (required), domain, dns_zone_id. Returns: errors, container, dns_records, proxy_hosts
teardown_serviceADestructive
Reverse expose_service: delete the proxy host for domain (found by name unless proxy_host_id is given) and, if dns_record_id is given, that DNS record. The exact plan is shown to the person first.
Inputs: domain (required), dry_run, dns_zone_id, dns_record_id, +1 more. Returns: note, errors, dry_run, planned, +3 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools are clearly separated by resource and action: Docker container/image/inventory tools, proxy resource tools, DNS zone/record tools, and diagnostic/overview tools. The main overlap is between high-level composite tools (expose_service, teardown_service, service_status, infrastructure_overview) and the lower-level resource tools, which can require judgment about which abstraction to use.
All names use snake_case, but the convention is mixed: some are plural resource nouns (proxy_hosts, docker_containers, dns_records), some are module/status nouns (homelab_modules, homelab_health, service_status), and some are verb_noun action tools (diagnose_service, expose_service, teardown_service). The names are readable, but there is no single predictable pattern.
Sixteen tools is reasonable for a homelab management server spanning Docker, reverse proxy, DNS, diagnostics, and service lifecycle. The count is slightly high because composite tools coexist with granular resource tools, but each tool still has a plausible role.
The surface covers core homelab workflows well: Docker inspection and lifecycle, proxy hosts/redirections/certificates/access lists, DNS zones/records, diagnostics, exposure/teardown, and status overview. Some gaps remain, such as management operations for tunnels, Authentik, uptime monitoring, and Docker volumes/networks beyond read-only inventory.
Maintenance
Related MCP Connectors
Manage hosts, redirects, SSL, and traffic analytics from Claude and other AI assistants.
Hosting for AI agents: your AI client deploys Docker apps to live HTTPS URLs over MCP.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Manage your own cloud with AI: deploy apps, push and ship custom Docker images, manage resources via your AI agent.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Nginx Proxy Manager instances through natural language, covering 28 tools for proxy hosts, certificates, streams, and more.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Nginx Proxy Manager, including proxy hosts, SSL certificates, streams, and more.4 npmISC
- AlicenseBqualityCmaintenanceEnables AI agents to manage Nginx Proxy Manager (reverse proxies, streams, redirects, and Let's Encrypt certificates) through natural language commands.3023 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables conversational management of Nginx Proxy Manager, including reverse-proxy routing, TLS certificates, access lists, and stream forwards, with built-in safety guardrails for production use.1MIT