convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
SikamikanikoBG

HomeLab Monitor

SikamikanikoBG/homelab-monitor

Dashboard self-hosted para homelab: GPU, containers, systemd e discos em uma página

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que expõe um dashboard de monitoramento de homelab em uma página única, cobrindo GPU, containers Docker, serviços systemd, discos e saúde de múltiplas máquinas via SSH. Permite que agentes Claude acessem os dados do laboratório com leitura total e em tempo real.

Instalação

$npx convez-ai SikamikanikoBG/homelab-monitor

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
238
Forks
37
Acompanhando
1
Saúde
71%
Último commit
há 1 dia
Versão
v0.38.1
Issues abertas
47
Contribuidores
5

Casos de uso

  • Monitorar em tempo real utilização de GPU e VRAM em modelos local-AI
  • Rastrear consumo de recursos (RAM, CPU, disco) entre múltiplos containers Docker
  • Conectar Claude como MCP client para investigar status da infraestrutura com linguagem natural
  • Gerenciar saúde de serviços systemd locais e remotos via SSH

Veredito

Ferramenta sólida para quem roda homelab/local-AI e quer visibilidade centralizada sem Prometheus/Grafana. O MCP server integrado é o grande diferencial — permite consultas naturais via Claude sobre estado da infraestrutura, ideal para automação e troubleshooting rápido.

README

A tradução para o português deste README ainda está na fila.

🛰️ HomeLab Monitor

GitHub stars version license docker docs

One page for your whole home lab & AI rig — GPU, containers, services, disks. No agents, no Prometheus/Grafana, no cloud.

Your home lab grew into a couple of machines, a Pi, and a GPU that's mysteriously always busy. HomeLab Monitor gives you one self-hosted page that answers the real questions: which model is holding the GPU, which container is eating RAM, what's filling your disks, and is anything down — across every box over SSH: Linux, a Pi, even Windows. Readable from your phone over the VPN.

Get started

# Grab the compose file and go. No GPU required — the GPU panels just light up when one's present.
curl -fsSLO https://raw.githubusercontent.com/SikamikanikoBG/homelab-monitor/main/docker-compose.yml
docker compose up -d

Open http://<your-host>:9800 and you're done. Full options (from source, GPU toolkit, Windows/WSL2) → Install docs.

🆕 v0.14.0 — a built-in read-only MCP server: connect Claude (or any MCP client) to your homelab and explore it with full dashboard parity, no extra container. Release notes · changelog · MCP docs.

What you get

Overview / All hosts

  • GPU, demystified — live VRAM/util/power/temp, and which container is holding the card (auto-mapped).
  • Containers, honestly — health plus RAM and VRAM in separate columns (real resident RAM, not page cache).
  • systemd services — local or remote, your own units highlighted, failures first.
  • WizTree-style disk treemaps — scan a filesystem, drill into folders, find the space hogs.
  • Multi-machine over SSH — paste one key per box; Linux, a Pi, even Windows. No agents, no installs.
  • Push alerts — Discord and ntfy.sh, edge-triggered so they don't spam.

Full tab-by-tab tour → Features.

Multi-machine, in two sentences

Open the Hosts tab, paste the hub's auto-generated SSH key onto each remote, and the hub starts polling it — no agents, just SSH + Python 3 (PowerShell on Windows). The hub pipes a small self-contained probe over SSH; nothing persists on the remote.

Onboarding, Windows setup, and the security model → Multi-machine docs.

Configuration

Set these under environment: in docker-compose.yml (all optional):

VariableDefaultMeaning
SAMPLE_INTERVAL10Seconds between samples
RETENTION_DAYS180How long history is kept
PRESSURE_FREE_MB2048Free VRAM below this counts as "pressure"
PORT9800Dashboard port
MCP_PORT9810Port for the built-in read-only MCP server
ENABLE_MCP1Set 0 to run the dashboard without the MCP server
WATCH_CONTAINERS—Extra containers to scan for OOM (comma-separated)
WATCH_SERVICES—systemd units to always show, even vendor ones (comma-separated)
CHECK_UPDATEStrueSet false to disable the daily GitHub-releases check (no outbound calls)

History lives in ./data/gpu.db (a bind mount), so it survives restarts and upgrades. Alerts, the systemd D-Bus mount, and per-server tuning → Configuration docs.

Under the hood

The hub stitches nvidia-smi, the Docker API, model-server APIs (Ollama, vLLM, llama.cpp, A1111, …), systemd D-Bus, and /proc + /sys into one sampled view, persisted to SQLite and downsampled on read so a six-month range loads as fast as the last hour. Single page, vendored Chart.js, no build step.

Connect an AI agent (MCP)

Your homelab is now legible to AI agents — point a client at one URL and it can see every host, container, GPU and disk. Read-only, no extra setup.

HomeLab Monitor isn't just a dashboard for you anymore; it's context for your AI agent too. A read-only MCP server is built into the same container (served on :9810) — so Claude, Claude Code, or any MCP client connects in one line and explores your whole lab through 12 named tools, with the same coverage you see on the dashboard: hosts, containers, systemd services, GPU and who's driving it, per-process RAM, AI model servers, disk treemaps, history and alerts.

# the dashboard is on :9800; the MCP server rides along on :9810
claude mcp add --transport http homelab http://YOUR-HUB:9810/mcp

Once connected, skip the tab-hunting and just ask — the agent picks the right tools:

  • "My GPU's been pinned for an hour — which model server is loaded, and who's actually calling it?"
  • "What's eating /backup? Give me the biggest folders and flag anything that looks like runaway logs."
  • "Which host is lowest on RAM right now, and what's the top process holding it?"
  • "I want to reboot and run an OS upgrade this weekend — which box needs it most, and what's a safe order given what's running on each?"

Read-only by design — there are no write tools, so an agent can look but never touch your fleet. Turn it off anytime with ENABLE_MCP=0. Full tool list & setup → MCP docs.

Security

This is a host monitor: it runs with host access and a read-only Docker socket, root mount, and D-Bus socket — a broad footprint by design. Keep it behind your LAN/VPN/firewall and don't expose it to the public internet. Details → docs.

⭐ Support the project

If HomeLab Monitor saves you a browser tab or two, a ⭐ on GitHub genuinely helps other home-labbers find it. Thank you!

Contributing

Issues and PRs are very welcome — especially new model-server probes, new monitors, and GPU back-ends. This is a hobby tool meant to help fellow home-labbers, so be kind. See CONTRIBUTING.md.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados