homelab-mcp
This server is an MCP endpoint that exposes a homelab's monitoring, infrastructure, media, storage, DNS/network, location, DevOps/AI, knowledge, aggregation, and write operations as simple LLM-friendly tools.
Get one-call overviews: complete homelab status, media stack status, infrastructure status, unified 24-hour change timeline, and prioritized attention list.
Inspect individual entities: host health, service health, service/host/IP lookup, and full dependency chains.
Search homelab documentation and check data freshness; force registry or doc refreshes when needed.
Run raw monitoring queries against Prometheus and Loki, and fetch web pages as clean markdown (with SSRF protection).
Manage media and downloads: Plex streams, Sonarr/Radarr queues, Transmission torrents, Overseerr requests, and Prowlarr health.
Control infrastructure: restart containers (including dependency-aware safe restarts), create/update/move Vikunja tasks and comments, create tasks from alerts, approve/decline Overseerr requests, and send ntfy notifications.
Explore the built-in knowledge base: services, hosts, IPs, topology, baselines, docs, stacks, and vault notes.
Reports Backblaze B2 storage usage and bucket health.
Inspects Docker containers across hosts, shows container counts and health, and supports restart operations.
Provides access to Gitea repositories, pull requests, and CI runs, and serves as a source for docs, stacks, and vault content.
Manages reverse proxy hosts and certificate status via NPM (Nginx Proxy Manager).
Sends push notifications through ntfy.
Provides active stream information and library statistics from Plex.
Lists and inspects Docker containers across hosts via Portainer.
Queries Prometheus metrics and provides summary health for hosts, containers, GPU, and storage.
Reports Proxmox node status and VM/CT inventory and health.
Shows Radarr upcoming releases, wanted items, and queue status.
Performs web searches through SearXNG.
Shows Sonarr upcoming releases, wanted items, and queue status.
Reports NAS status and storage utilization from Synology.
Lists torrents and download queue status from Transmission.
Shows WireGuard VPN peers and their connection status.
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-mcp what's the overall health of my homelab?"
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-mcp
A FastMCP server that puts an entire homelab behind a single MCP endpoint. It exposes 85 tools across 29 services (Prometheus, Loki, Proxmox, Portainer, Plex, Sonarr/Radarr, Synology, PBS, Backblaze, Technitium DNS, Gitea, WireGuard, OwnTracks, ntfy, and more) so that any LLM — a small local model or a cloud one — can answer "what's going on in the lab?" with one tool call, no PromQL, no multi-step reasoning, no per-service API knowledge.
Key features
Summary-first tool design. Every tool returns a complete, pre-digested answer (e.g.
get_homelab_overview,what_needs_attention,explain_host_health). Raw query tools (query_prometheus,query_logs) exist but are secondary. Tool docstrings double as MCP descriptions, tuned so small local LLMs pick the right tool.85 tools across 29 services, organized into 39 tool modules plus a built-in knowledge base (services, hosts, IPs, docs, compose stacks, topology graph).
Conditional registration. Each tool module checks its env vars at startup and skips registration when credentials are missing — a partial
.envyields a smaller but fully working server, never a broken one.Dual transport. stdio by default (for local MCP clients), streamable-http via
MCP_TRANSPORT(for network clients). HTTP mode adds an OIDC + trusted-LAN auth chain.Mostly read-only. Eleven write tools exist (container restarts, Vikunja tasks, kanban moves and task comments, Overseerr approvals, image updates, ntfy push notifications); writes are audit-logged to Loki and support
dry_run=True.
Related MCP server: homelab-ai
Architecture
server.py entrypoint: lifespan, auth chain, /health route, tool registration
└─ lifespan one long-lived httpx.AsyncClient per configured service,
created inside an AsyncExitStack; session-auth services
(Transmission, Synology, Technitium, wg-easy, NPM, B2, MySpeed)
are wrapped in lib/auth.py's SessionAuthManager
└─ tools/*.py one module per service; each exposes register(mcp) and
self-skips when its config.py env vars are unset
└─ config.py env-driven config (python-dotenv) + knowledge loaders
└─ data/ services.yaml, hosts.yaml, topology.yaml, baselines.yaml,
docs/, stacks/, vault/ — synced from other repos via
`make sync-data` locally; fetched live from Gitea in prod,
refreshed by a background task on a configurable intervalTools return plain dicts (FastMCP serializes to JSON); errors are never raised to the client, they come back as {"error": <code>, "message": <human-readable>}.
Quickstart
Requires Python 3.13+ and uv.
uv sync # install deps from uv.lock
make pull-env # hydrate .env from Infisical (see below)
make dev # stdio transport (for Claude Desktop / MCP clients)
make http # streamable-http on port 8000 (override with MCP_PORT)make pull-env fetches every key from the Infisical secret store using the scoped read-only machine identity in ~/.config/infisical/homelab-mcp.env, and writes .env at mode 0600. If a .env.local exists it is appended after the pulled block, so local-only overrides win (python-dotenv takes the last occurrence). Running the server against your own infrastructure instead? Skip Infisical and use cp .env.example .env, filling in URLs/keys for the services you have.
Only the services you configure get registered — an empty .env still starts, with just the credential-free tool groups.
The knowledge tools (service/host/IP lookup, topology, baselines) read four seed files: data/hosts.yaml, data/services.yaml, data/topology.yaml, data/baselines.yaml. The server boots fine without them — the knowledge tools just start empty. To create them for your own infrastructure:
uv run scripts/bootstrap_registries.py # or --dry-run to previewThis discovers hosts and services from whatever you configured in .env (Proxmox, Portainer, Scanopy, NPM, Prometheus) and writes skeleton YAMLs with TODO markers for the fields only you know: role descriptions, the cross-service aliases map (which upstream name maps to which host — cross-tool joins depend on it), dependency edges, and the never-restart container list. Alternatively, copy the data/*.example.yaml files (shipped in the public mirror) and edit by hand.
Docker / production
docker compose up -d # builds the image, serves streamable-http on :5774
curl localhost:5774/health # {"status": "ok", "version": "..."}The image (multi-stage uv build on python:3.13-slim) defaults to MCP_TRANSPORT=streamable-http and MCP_PORT=5774, with a Docker HEALTHCHECK polling /health. data/stacks, data/docs, and data/vault are stripped at build time and fetched live from Gitea at runtime instead.
Production runs on the beast host via Gitea CI (.gitea/workflows/ci.yml): quality gates on every branch, and on a master push it builds a CalVer+SHA-tagged image, pushes to the Gitea registry, renders stack/docker-compose.yaml with the pinned tag, deploys over SSH, and polls /health until the new version reports live. CI never ships secrets: beast's .env is rendered by the host's Infisical agent from the /beast/homelab-mcp folder of the homelab-infra store, and the deploy only asserts that the file exists. To rotate a secret, change it in Infisical, give the agent ~60 seconds to re-render, then docker compose up -d --force-recreate homelab-mcp — a container's environment is frozen at process start, so a re-render alone does not reach the running server.
In HTTP mode the server authenticates via a MultiAuth chain: Authentik OIDC (JWT verification) for external traffic, plus a LAN bypass that trusts direct, un-proxied requests from MCP_TRUSTED_CIDRS (default 192.168.1.0/24,127.0.0.0/8).
Configuration
All configuration is environment variables, loaded by python-dotenv from .env (local dev) or injected via env_file: (Docker). See .env.example (with config.py as the authoritative list) — roughly 75 vars, almost all of the form <SERVICE>_URL + <SERVICE>_API_KEY/token/password.
There is no validation layer on purpose: a missing var simply means that service's tools are not registered. Non-service knobs include MCP_TRANSPORT, MCP_PORT, MCP_TRUSTED_CIDRS, REFRESH_INTERVAL_SECONDS, and DOC_REFRESH_INTERVAL_SECONDS.
Tool catalog
Area | Modules | What you get |
Monitoring | prometheus, loki, healthchecks, myspeed, internet_health | Host/container/GPU/storage health, recent errors, container logs, cron check status, speed tests, external internet health score with trend and variance windows plus provider outages, raw PromQL/LogQL |
Infrastructure | proxmox, docker, npm, crowdsec | Proxmox nodes and VMs/CTs, containers across hosts (Portainer), reverse-proxy hosts and certs, CrowdSec alerts and decisions |
Media | plex, tautulli, sonarr, radarr, overseerr, transmission, prowlarr | Streams, library stats, upcoming/wanted, requests, torrents, indexer health |
Storage | synology, pbs, backblaze | NAS status, backup jobs and datastores, B2 usage |
DNS / Network | technitium, wireguard, scanopy | DNS lookups and zone records, VPN peers, network topology and IP info |
Location | owntracks | Where each tracked device is now (coordinates, battery, connection, named regions), device-health inventory, movement history with distance and longest stop, recorder health |
DevOps / AI | gitea, litellm, llama, searxng | Repos, PRs, CI runs, LLM proxy status, llama-server slots/metrics, web search and page fetch |
Knowledge | knowledge, graph, freshness, baselines, refresh | Service/host/IP lookup, docs search, dependency chains, "is this normal?" baseline comparison, forced registry/doc refresh |
Aggregation | aggregation, compound, health, changefeed | One-call overviews (homelab/media/infra), |
Write ops | docker, compound, vikunja, overseerr, ntfy |
|
To see exactly what's registered against your .env, connect any MCP client and issue a tools/list request — the set varies with configured credentials.
Development
make test # pytest, 689 tests
make lint # ruff check + format check
make format # ruff format + autofix
make hooks # point git at .githooks (pre-commit: ruff on staged Python files;
# pre-push: full lint + test suite)
make sync-data # rsync docs/stacks/vault from sibling repos into data/Tests mock httpx transports; nothing in the suite touches the real lab.
Project layout
server.py entrypoint, lifespan, auth, tool registration
config.py env config + knowledge loaders
resources.py MCP resources
lib/ auth (session managers), hosts, audit, meta, http (shared request ladder),
redact, refresh facade (refresh_registries/refresh_content), per-service helpers
tools/ 38 tool modules, one register(mcp) each
scripts/ bootstrap_registries.py (registry generator), pull_env.py (.env from Infisical) + publish tooling
tests/ pytest suite (689 tests)
data/ knowledge base (synced/fetched, not source code)
docs/ operational references (e.g. the Crow's Nest tool rename map)
stack/ production compose file rendered by CI
Dockerfile multi-stage uv build
docker-compose.yml local container run
.gitea/workflows/ CI + deploy pipeline
.githooks/ pre-commit / pre-push hooksHonest notes
Self-signed certs: the Proxmox, PBS, Portainer, and Synology clients use
verify=False. Fine for a LAN homelab, not a pattern to copy anywhere TLS actually matters.Write tools: deliberately few, all audit-logged to Loki, all previewable with
dry_run=True. Still — an LLM with this server can restart your containers. Configure only the credentials you're comfortable delegating.Scope: built for a single user on a trusted LAN (
192.168.1.0/24). The LAN-bypass auth grants full access to any un-proxied client in the trusted CIDRs, and there is no per-tool authorization. External access is expected to come through a reverse proxy with OIDC in front.Knowledge freshness: registry/doc data refreshes on a timer and can drift between refreshes; responses include staleness metadata, and
refresh_registries/refresh_docsforce an update.
Available Tools
16 toolsexplain_host_healthARead-only
Get detailed health data for a specific host: resource usage, services running on it, and any issues detected.
Inputs: host_name (required). Returns: object
explain_service_healthARead-only
Get detailed health data for a specific service: current status, where it runs, what depends on it, and any issues detected.
Inputs: service_name (required). Returns: object
fetch_pageARead-only
Fetch a web page and extract its content as clean markdown. Strips navigation, ads, and boilerplate.
Only http/https URLs are fetched. Loopback, link-local, and cloud-metadata targets are always blocked; private/RFC1918 targets are blocked unless FETCH_ALLOW_PRIVATE is set (default allows LAN fetches). Redirects are re-validated at every hop.
Inputs: url (required). Returns: object
get_homelab_overviewARead-only
Complete homelab overview: host health, container counts, storage utilization, active media streams, recent errors, and speed test results. Returns partial results if individual services are unreachable.
Inputs: no named parameters. Returns: object
get_host_infoARead-only
Look up a host by name or IP. Returns specs, role, OS, and all services running on it.
Inputs: name_or_ip (required). Returns: object
get_infra_overviewARead-only
Infrastructure overview: Proxmox node status, Docker container counts per host, storage utilization (NAS, PBS, Backblaze), CrowdSec security status, and NPM proxy status.
Inputs: no named parameters. Returns: object
get_ip_infoARead-only
Reverse-lookup an IP address. Returns the host and all services at that IP.
Inputs: ip (required). Returns: object
get_media_overviewARead-only
Media overview: Plex active streams, Sonarr/Radarr upcoming and queues, Transmission downloads, Overseerr requests, and Prowlarr indexer health.
Inputs: no named parameters. Returns: object
get_service_infoARead-only
Look up a service by name. Returns host, port, stack, domain, role, and co-located services.
Inputs: name (required). Returns: object
refresh_docsAIdempotent
Force an immediate refresh of documentation, Docker stacks, and vault notes from Gitea repositories. Returns a summary of what changed.
Inputs: no named parameters. Returns: object
refresh_registriesAIdempotent
Force an immediate refresh of service and host registries from all live API sources (Portainer, Proxmox, DNS, NPM, Scanopy, WireGuard, Healthchecks, Gitea). Returns a summary of what changed.
Inputs: no named parameters. Returns: object
search_docsARead-only
Full-text search across all homelab documentation. Returns matching paragraphs with source file and section.
Inputs: query (required), max_results. Returns: object
show_data_freshnessARead-only
Check connectivity and freshness status for all configured services. Returns which data sources are reachable and which are not.
Inputs: no named parameters. Returns: object
show_dependency_chainARead-only
Show the full dependency chain for any homelab entity. Returns what it runs on, what depends on it, what it depends on, how it is accessed (ingress), and what storage it uses.
Inputs: entity (required). Returns: object
what_changed_last_24hARead-only
Get a unified timeline of recent events across the homelab: alerts, target flaps, failed checks, security bans, expiring certs, and backup issues.
Inputs: hours. Returns: object
what_needs_attentionARead-only
Get a prioritized list of things that need attention right now. Checks host resources, Prometheus target health, cron (Healthchecks) status, security events (CrowdSec), and SSL certificate expiry. Returns verdicts sorted by severity. (Does not check backups -- use get_pbs_status.)
Inputs: no named parameters. Returns: object
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 have clearly distinct purposes, but pairs like get_service_info vs explain_service_health and get_host_info vs explain_host_health could be confused since they cover the same entity with different details. The overview tools (homelab, infra, media) also have overlapping metrics but are scoped clearly enough.
All names use lowercase_snake_case and follow a verb-first pattern (search_, get_, show_, explain_, fetch_, refresh_). The two 'what_' tools deviate from strict verb_noun but are still clear and consistent in style.
16 tools is slightly above the typical 3-15 well-scoped range, but the homelab monitoring domain is broad and each tool addresses a distinct aspect. The count feels justified rather than excessive.
The set covers most read-only monitoring needs: info lookup, health, overviews, change timeline, and refresh actions. However, what_needs_attention explicitly references get_pbs_status for backup checks, but that tool is not actually in the set, a notable gap. There are also no control/mutation tools, which may be intentional but limits the surface.
Maintenance
Related MCP Connectors
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceAn MCP server that gives AI assistants control over your Sonarr, Radarr, Prowlarr, qBittorrent, and Jellyfin homelab media stack.8MIT
- AlicenseNot gradedqualityCmaintenanceSelf-hosted AI orchestrator that monitors and manages homelab services, exposing them as MCP tools for LLMs to drive.4MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI assistants real-time access to your homelab infrastructure. It enables querying node status, managing Docker containers, controlling Proxmox VMs, and inspecting OPNsense firewall state through natural conversation.51 PyPI2MIT
- FlicenseNot gradedqualityBmaintenanceA self-hosted MCP server for homelabs with ~193 tools covering media, home automation, productivity, infrastructure, and public APIs, featuring a web dashboard for configuration and health monitoring.2-