Homelab Infra Mcp

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.

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.

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"      }    }  }}

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.

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

Third-party, under their own licenses

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.

Develop

uv venv -p 3.11 .venv && uv pip install -e '.[dev]'.venv/bin/pytest -qpython3 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.