homelab-mcp
Provides read-only access to Prometheus metrics for homelab monitoring, including host CPU/RAM/disk/load summaries, disk and resource trends, scrape target status, and container status derived from Prometheus queries.
Checks Uptime Kuma monitor status, reporting monitors that are down, pending, or under maintenance, as well as certificates expiring within 14 days.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
homelab-mcp
A small, read-only MCP server that gives an AI agent (here: Hermes Agent) real numbers about a homelab server, measured by Prometheus, so it never has to guess them.
Code collects the facts; the AI only explains them.
Architecture
Discord ─► Hermes (container) ──mcp_internal (internal)──► homelab-mcp (container) ──mcp_prom──► Prometheus (host :9090)
│ br-hermes: internet only no internet, no host except :9090 │
✗ host services, other containers ▼
node-exporter ◄── textfile collector ◄── host cron
(CPU, RAM, disk, load) (containers, apt, reboot, backup age)Related MCP server: MCP SSH SRE
Tools (all read-only, fixed PromQL)
No tool accepts PromQL. Inputs are enums or bounded integers, validated by the MCP SDK before a tool runs; queries are
built only from templates in src/homelab_mcp/queries.py.
Tool | Inputs | Returns |
| none | CPU %, RAM %, root disk % (df formula), load 1/5/15, cores, uptime, pending apt (all/security), reboot required, last backup age |
|
| root disk % now vs then, change, days until full ( |
|
| min / avg / max over the window |
| none | Prometheus scrape targets up/down, textfile collector errors |
|
| containers not running, crash restarts, (re)started in window, unhealthy, data age |
| none | Uptime Kuma monitors down/pending/maintenance, certificates expiring < 14 days |
Every result includes as_of; missing data is null, never a guess.
Security model
Layer | Control |
Inputs | No raw PromQL; enums and bounded ints only; only |
Auth |
|
HTTP | MCP SDK DNS-rebinding protection: only |
Container | non-root (10001), |
Supply chain | base image pinned by digest ( |
Network |
|
Layout
src/homelab_mcp/ queries.py (PromQL templates) · prometheus.py (client) · tools.py · server.py · app.py (auth, HTTP)
tests/ query validation, tool logic against a fake Prometheus, auth + MCP handshake
host/ textfile-metrics.sh (cron) · node-exporter.compose.yaml · homelab-isolation.nft + .serviceRun
cp .env.example .env && chmod 600 .env # set HOMELAB_MCP_TOKEN (same value in the agent's .env)
docker build --target test . # runs the test suite; the build fails if a test fails
docker compose up -d --buildAgent side (Hermes config.yaml):
mcp_servers:
homelab:
url: http://homelab-mcp:8000/mcp
headers: { Authorization: "Bearer ${HOMELAB_MCP_TOKEN}" }
tools: { include: [host_summary, disk_trend, resource_trend, targets_status, container_status, service_checks] }Host side
host/textfile-metrics.sh, every 5 min from cron: per-container running / restart count / health / start time; hourly: pending apt upgrades (simulated) and reboot-required. Written atomically for node-exporter's textfile collector.host/node-exporter.compose.yaml: node-exporter pinned by digest, textfile directory mounted read-only.host/homelab-isolation.nft+.service: an own nftables table (never touches Docker's or Tailscale's rules), loaded at boot after Docker.
Updating dependencies
docker run --rm --user "$(id -u):$(id -g)" -e HOME=/tmp -v "$PWD":/src -w /src python:3.13-slim \
sh -c 'pip install -q --user uv && ~/.local/bin/uv pip compile --generate-hashes --python-version 3.13 \
--python-platform x86_64-unknown-linux-gnu -o requirements.txt requirements.in'Then rebuild with --target test before deploying.
License
MIT, see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Heartbeat and tokens/sec monitoring for self-hosted LLM servers (Ollama etc.), with down alerts.
Heartbeat and tokens/sec monitoring for self-hosted LLM servers (Ollama etc.), with down alerts.
Keyless, read-only checks of Intentrax AI-agent execution proofs. Never executes, signs, or writes.
Real Linux labs your AI agent deploys, routes and runs, with domains, TLS, DBs and an audit log.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to query Prometheus metrics, monitor alerts, and analyze system health through read-only access to your Prometheus server with built-in query safety and optional AI-powered metric analysis.MIT
- AlicenseNot gradedqualityDmaintenanceProvides read-only server monitoring and diagnostic tools for AI assistants to manage Linux and Unraid systems via SSH. It enables natural language interactions for container management, storage health checks, and system log analysis while keeping credentials secure.17ISC
- AlicenseAqualityDmaintenanceProvides read-only access to host system metrics (CPU, memory, disk), Docker container health/logs, and sandboxed log file analysis via MCP tools, enabling AI agents to monitor enterprise infrastructure safely.3MIT
- AlicenseAqualityBmaintenanceGives AI agents safe, bounded, non-blocking access to Linux sysadmin inspection tasks, including CPU, RAM and disk healthchecks, memory-safe log tailing with regex filtering, and user-level systemd service and timer auditing. All operations run without sudo or unrestricted root shells, avoiding interactive pager hangs and context window flooding.478 PyPI1MIT