Skip to main content
Glama
homelab-mcp

homelab-mcp

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

host_summary

none

CPU %, RAM %, root disk % (df formula), load 1/5/15, cores, uptime, pending apt (all/security), reboot required, last backup age

disk_trend

days 1–14 (default 7)

root disk % now vs then, change, days until full (deriv), or "not filling"

resource_trend

metric cpu/ram/load1, hours 1/6/24/168

min / avg / max over the window

targets_status

none

Prometheus scrape targets up/down, textfile collector errors

container_status

hours 24/168

containers not running, crash restarts, (re)started in window, unhealthy, data age

service_checks

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 GET /api/v1/query is ever called

Auth

Authorization: Bearer <HOMELAB_MCP_TOKEN> on every request (constant-time compare); refuses to start with a missing, placeholder or < 32-char token

HTTP

MCP SDK DNS-rebinding protection: only Host: homelab-mcp:8000

Container

non-root (10001), read_only + 16 MB noexec tmpfs, cap_drop: ALL, no-new-privileges, 64 pids, 128 MB RAM, 0.25 CPU, no published ports, no Docker socket, no host mounts

Supply chain

base image pinned by digest (python:3.13-slim@sha256:e48f59cdba69…); every dependency hash-locked (pip install --require-hashes --no-deps)

Network

mcp_internal is internal: true; host firewall (host/homelab-isolation.nft) blocks Hermes from all host services and other containers, lets homelab-mcp reach only Prometheus :9090, no internet

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 + .service

Run

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 --build

Agent 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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.
      17
      ISC
    • A
      license
      A
      quality
      D
      maintenance
      Provides 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.
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Gives 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.
      4
      78 PyPI
      1
      MIT