Homebutler

What Higangssh/homebutler MCP server does

Higangssh/homebutler MCP server provides a structured interface for operating and inspecting homelab infrastructure. Its coverage includes local system resources, Docker containers, Proxmox VE clusters, network discovery, open ports, Wake-on-LAN, resource alerts, inventory, reports, and operational diagnoses. The interface is designed for agents that need bounded actions and explicit results instead of unrestricted SSH shell access.

Proxmox tools expose cluster, node, guest, and task information. They also support starting, rebooting, and gracefully shutting down one explicitly named guest after confirmation. Docker tools list containers, retrieve logs and resource statistics, inspect configuration without returning environment variable values, show processes, and restart or stop containers. Read-only tools cover system status, process lists, ports, network devices, and configured checks.

How it works

The project is distributed as a single Go binary with no runtime dependencies described in the README. It can be used from the terminal, scripts, cron, a web dashboard, or MCP clients. For change reporting, HomeButler stores snapshots under ~/.homebutler/reports/snapshots/ and compares later runs with the latest saved baseline. Reports distinguish events such as new, gone, replaced, image, state, port, disk, and skipped changes.

Higangssh/homebutler MCP server also exposes report-oriented operations. report summarizes health, warnings, notable changes, and suggested commands. doctor performs a read-only preflight covering resource pressure, stopped containers, public ports, backup hygiene, notifications, report-baseline readiness, and configured Proxmox endpoint reachability. Watch tools record or inspect Docker restart incidents; systemd and PM2 targets are reported as skipped by the one-shot watch check rather than treated as healthy.

Setup and configuration

The README documents an install script that auto-detects the operating system and architecture, a Homebrew installation, and an interactive homebutler init command for adding servers. The binary can then run status, Docker, inventory, report, watch, and web-dashboard commands. JSON output is available for several CLI workflows, including status, inventory scans, and reports.

Configuration validation is available through the config_validate MCP tool. It reports which configuration file was used, which rule selected it, what was read from each section, and errors or ignored settings. The provided material does not specify configuration keys, SSH credential fields, Proxmox token variables, or a dedicated command for launching the MCP transport, so those details should be verified in the project documentation before deployment.

Tools and capabilities

Higangssh/homebutler MCP server includes tools for:

• Reading system CPU, memory, disk, uptime, and top-process information.
• Listing, inspecting, logging, monitoring, restarting, and stopping Docker containers.
• Querying Proxmox versions, nodes, guests, resources, tasks, and task status.
• Starting, rebooting, or shutting down explicitly targeted Proxmox guests.
• Listing curated Proxmox Community Scripts and rendering pinned commands without executing them.
• Sending Wake-on-LAN packets, scanning local networks, and listing open ports with process information.
• Building inventory exports, health reports, alerts, diagnoses, and restart histories.

Limitations and notes

The server does not provide unrestricted shell access through the described MCP tools. Proxmox script commands are rendered for human review and are not fetched or executed by the tool. Docker process inspection is read-only and does not offer exec or TTY access. Watch checks only inspect Docker targets; systemd and PM2 targets are skipped. Captured logs are excluded from restart history unless explicitly requested, and Docker inspection omits environment variable values.