A Read-Only Homelab MCP Server (FastMCP)

# A read-only homelab MCP server: read tools + read-only creds only.
# Full walkthrough: /articles/read-only-homelab-mcp-server

# 1. Isolated Python env with FastMCP.
python3 -m venv /opt/homelab-mcp/venv
/opt/homelab-mcp/venv/bin/pip install fastmcp requests

# 2. The server. Read-only by design: only query tools, no write/delete/create.
#    Point PROM_URL at your Prometheus; keep any token in a secret store + env.
cat > /opt/homelab-mcp/server.py <<'PY'
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()
PY

# 3. Smoke-test over the real MCP protocol (in-memory client) BEFORE wiring a chat client.
cat > /opt/homelab-mcp/test_client.py <<'PY'
import asyncio
from fastmcp import Client
from server import mcp
async def main():
    async with Client(mcp) as c:
        print([t.name for t in await c.list_tools()])
        print((await c.call_tool("cluster_targets_up", {})).data)
asyncio.run(main())
PY
cd /opt/homelab-mcp && PROM_URL="http://10.0.0.104:9090" venv/bin/python test_client.py

# 4. Register it in your MCP client (Claude Desktop / Claude Code):
#    "mcpServers": { "homelab-readonly": {
#        "command": "/opt/homelab-mcp/venv/bin/python",
#        "args": ["/opt/homelab-mcp/server.py"],
#        "env": { "PROM_URL": "http://10.0.0.104:9090" } } }