DEV Community: Josh Hall

Build a Read-Only Homelab MCP Server for Your LLM

Josh Hall — Sun, 06 Sep 2026 18:28:52 +0000

I wanted to ask my AI assistant plain questions about my homelab — "are all my nodes up?", "any firing alerts?" — and get real answers from the real cluster. What I absolutely did not want was to hand a language model a button that could reboot a node or delete a VM. Convenience is lovely right up until the model confidently does the wrong thing at 2 a.m.

The fix is a read-only MCP server: a small program that exposes your homelab to an AI as query tools and nothing else, connecting with credentials that can only read. The safety isn't a promise you extract from the model — it's baked into the architecture. There is simply no tool, and no permission, to change anything. Every number below came out of my own running cluster.

Make the addresses your own. Replace 10.0.0.104 with your Prometheus host. Keep the read-only API token in your secret store and pass it via an environment variable — never paste a real token into the server file.

What MCP is, in one minute

The Model Context Protocol (MCP) is an open standard — originally from Anthropic — for connecting AI assistants to tools. An MCP server publishes typed-function tools; an MCP client (Claude Desktop, Claude Code, and a growing list) lets the model discover and call them. Instead of hallucinating your cluster's state, the model asks your server and gets the real answer.

The protocol is neutral about safety — a tool can do anything you program. Which is why the interesting decision is what you choose to expose. We expose only reads.

Build the server

I'll use Python and FastMCP, where a decorated function becomes a tool. Two tools is enough to be genuinely useful: a general Prometheus query, and a friendly "are my targets up?" summary.

import os, requests
from fastmcp import FastMCP

PROM_URL = os.environ.get("PROM_URL", "http://10.0.0.104:9090")
mcp = FastMCP("homelab-readonly")

@mcp.tool
def prometheus_query(promql: str) -> dict:
    """Run a read-only Prometheus instant query."""
    r = requests.get(f"{PROM_URL}/api/v1/query",
                     params={"query": promql}, timeout=10)
    r.raise_for_status()
    data = r.json()["data"]["result"]
    return {"query": promql, "series": len(data),
            "sample": [{"metric": s["metric"], "value": s["value"][1]}
                       for s in data[:5]]}

@mcp.tool
def cluster_targets_up() -> dict:
    """How many scrape targets are up vs down (read-only)."""
    r = requests.get(f"{PROM_URL}/api/v1/query",
                     params={"query": "up"}, timeout=10)
    r.raise_for_status()
    res = r.json()["data"]["result"]
    up = sum(1 for s in res if s["value"][1] == "1")
    return {"targets_total": len(res), "targets_up": up,
            "targets_down": len(res) - up}

if __name__ == "__main__":
    mcp.run()   # stdio transport by default

Notice what's not here: no reboot, no delete, no create. The tool surface is the security boundary.

FastMCP ships an in-memory client, so a five-line script exercises the real protocol. This is unedited output from my cluster:

tools/list -> ['prometheus_query', 'cluster_targets_up']
call cluster_targets_up  -> {'targets_total': 27, 'targets_up': 27, 'targets_down': 0}
call prometheus_query('count(smartctl_device_smart_status)')
                         -> {'series': 1, 'sample': [{'value': '8'}]}

Twenty-seven scrape targets, all up; eight disks reporting SMART. The model asked; the cluster answered; nothing changed.

Read-only by design — four layers

"Read-only" isn't one setting; it's a posture you build in layers, so a mistake at any single layer can't hand an AI the keys:

Read-only credentials — a Proxmox token bound to the built-in PVEAuditor role; a query-only DB user.
Read tools only — no write/delete tool is ever registered.
Bounded inputs — instant queries only, no admin endpoints.
Private scope — localhost / Tailscale, never the public internet.

The credential is the real lock. The single most important choice is the read-only credential. In Proxmox that's a token bound to PVEAuditor — it can read cluster state and nothing else. Even if you later fat-finger a write tool into the server, an audit token has no permission to carry it out.

Connect it to Claude

{
  "mcpServers": {
    "homelab-readonly": {
      "command": "python",
      "args": ["/opt/homelab-mcp/server.py"],
      "env": { "PROM_URL": "http://10.0.0.104:9090" }
    }
  }
}

Now you can ask, in plain English, "are all my Prometheus targets up?" and the assistant calls cluster_targets_up and tells you. I keep mine reachable only over Tailscale — available from my laptop or phone, never from the open internet.

The flourish: a fully self-hosted loop

Pair this with a local Ollama cluster behind a load-balancing endpoint and the whole loop is yours: a local LLM calling a read-only tool server to answer questions about your cluster — no cloud in the path, and no way for any of it to change a thing.

Read the full, updated versions

I keep the maintained versions of this and the surrounding series on my homelab site, documented from a working 4-node Proxmox cluster:

Originally published on peira.dev.

What Is the *arr Stack? Sonarr, Radarr, and Prowlarr Explained

Josh Hall — Sun, 06 Sep 2026 15:12:06 +0000

If you've spent any time in homelab or self-hosting circles, you've seen people mention their "Arr stack" — often written *arr, where the asterisk is a wildcard for Son*arr, Radarr, Lidarr*, and friends. It sounds like arcane jargon, but the idea is simple: a set of apps that turn "I want to watch this" into an organized file in your library without you touching a download client.

This post explains what each piece does and how they fit together — the concepts, no setup yet.

A note on use: the arr stack is just a tool. Point it only at content you have the legal right to download where you live — your own media, public-domain works, and Linux ISOs are the intended use.

The problem the Arr stack solves

Managing a media library by hand means searching a dozen indexers, squinting at release names to guess which is good, downloading, renaming the file into something your media server understands, moving it into the right folder, and refreshing the library. Then doing it again for the next episode. It starts as a hobby and quietly becomes a part-time job.

The Arr stack automates every step. You tell it what you want, and it handles the searching, grabbing, renaming, and filing, then tells your media server to rescan so the title just appears, ready to watch.

One thing I learned running this myself: "hands-off" holds right up until the auto-downloading quietly stops. Nothing errors — the library just stops growing, and because everything still looks fine, you don't catch it for a while. Build it so you'll notice when one link stops handing off to the next.

The players

Each app is a focused piece of the pipeline. All are open-source and part of the Servarr family, so they share a near-identical interface.

App	Handles	Thinks in terms of
Sonarr	TV shows	series → seasons → episodes
Radarr	Movies	single films + editions
Prowlarr	Indexers	the sources everything searches
A download client (e.g. qBittorrent)	The actual transfer	torrents / Usenet
A media server (Plex / Jellyfin)	Playback	libraries you stream

Sonarr and Radarr are essentially the same program with different logic — Sonarr understands episode numbering and air schedules, Radarr understands releases and cuts. There are siblings too: Lidarr (music), Readarr (books, now retired). Most media setups only need Sonarr and Radarr.

How Prowlarr changed the game

An indexer is a searchable catalog of available releases — a torrent tracker or a Usenet index. Before Prowlarr, you added every indexer to Sonarr and Radarr separately, kept two credential sets current, and repeated it every time an indexer changed.

Prowlarr is the indexer manager: you add each indexer once, and it syncs it into every connected Arr app automatically. Prowlarr stores the indexer definitions; Sonarr and Radarr register as "applications" and receive the synced indexers.

Prowlarr decides where to search; Sonarr and Radarr decide what to grab. Prowlarr never downloads anything — it just gives the others a shared, always-current list of places to look.

The pipeline, end to end

  You add a title  (or an import list adds it automatically)
        |
        v
  Radarr / Sonarr   -- decides it's "wanted", asks Prowlarr's indexers
        |
        v
  Prowlarr indexers -- return candidate releases, scored by quality rules
        |
        v
  Download client   -- grabs the chosen release (torrent behind a VPN)
        |
        v
  Radarr / Sonarr   -- imports: renames + moves the file into the library
        |
        v
  Media server      -- rescans; the title appears, ready to stream

Every arrow is automatic. The only human input is the first line — and even that can be automated with import lists that pull from a watchlist or "popular" feeds.

Where quality rules fit in

The Arr apps don't grab the first result they find. Each uses a quality profile — your rules for resolution, source, file size, and codecs — to score candidates and pick the best fit. The community-maintained TRaSH Guides are the reference for tuning these.

What about a VPN?

Only one piece needs one. Sonarr, Radarr, and Prowlarr move metadata and searches — no swarm traffic. The download client is what joins torrent swarms and exposes your IP, so the hardened setup routes only the torrent client through a VPN container with a kill-switch, leaving the rest on your LAN.

The wider *arr family

Bazarr watches your Sonarr and Radarr libraries and fetches subtitles automatically.
Lidarr does for music what Sonarr does for TV; Whisparr handles adult content.
For requests, Jellyseerr gives the household a streaming-style page that hands approved titles to Radarr/Sonarr.
One to skip: Readarr (books) was retired in 2025 when its metadata source broke.

Where to go next

I keep the full, continually-updated versions of these guides — deploy with Docker Compose, automation, subtitles, music, and requests — on my homelab site, documented from a working 4-node Proxmox cluster:

Originally published on peira.dev.