# Higangssh/homebutler [Health: Active]

**Category:** 📊 Monitoring  
**Repository:** https://github.com/Higangssh/homebutler  
**GitHub Stars:** 278  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/higangssh-homebutler

## Description
All-in-one homelab management MCP server. Monitor system resources, manage Docker containers, Wake-on-LAN, scan networks, check open ports, and run alerts — across multiple servers via SSH. Single 10MB binary, zero dependencies.

## Tools
Capabilities this server exposes over MCP:

- **proxmox_status** — Get Proxmox VE version, cluster status, and resources
- **proxmox_guests** — List Proxmox QEMU and LXC guests, optionally filtered by node, status, or type
- **proxmox_node** — Get detailed Proxmox node status
- **proxmox_tasks** — Get the 50 most recent Proxmox tasks for a node
- **system_status** — Get system status including CPU, memory, disk usage, and uptime
- **proxmox_guest_start** — Start one explicitly targeted Proxmox guest after confirmation and return the accepted task UPID
- **proxmox_guest_reboot** — Reboot one explicitly targeted Proxmox guest after confirmation and return the accepted task UPID
- **proxmox_guest_shutdown** — Gracefully shut down one explicitly targeted Proxmox guest after confirmation and return the accepted task UPID
- **proxmox_task_status** — Inspect one asynchronous Proxmox task by node and opaque UPID
- **proxmox_script_list** — List the curated Proxmox VE Community Scripts catalog (community-scripts/ProxmoxVE)
- **proxmox_script_command** — Render the pinned install command for one Proxmox VE Community Script. Never fetches or runs it; the caller reviews and runs it themselves on the Proxmox host
- **docker_list** — List Docker containers with their status, image, and ports
- **docker_restart** — Restart a Docker container by name
- **docker_stop** — Stop a Docker container by name
- **docker_logs** — Get logs from a Docker container
- **docker_stats** — Get resource usage statistics (CPU, memory, network, block I/O) for all running Docker containers
- **docker_top** — List the processes running inside a Docker container, read from the host. Read-only: no exec, no TTY
- **docker_inspect** — Summarize a Docker container's image, state, restart policy, ports, mounts, networks, and health. Environment variable values are never included
- **wake** — Send a Wake-on-LAN magic packet to wake a machine
- **open_ports** — List open network ports with associated process information
- **network_scan** — Scan the local network to discover devices (IP, MAC, hostname)
- **alerts** — Check resource alerts for CPU, memory, and disk usage against configured thresholds
- **inventory_scan** — Collect server inventory/topology including system status, Docker containers, app ports, and system ports
- **inventory_export** — Export server inventory/topology as a Mermaid diagram locally, or JSON locally/remotely
- **report** — Generate a butler-style health report with snapshot comparison, warnings, notable changes, and suggested actions
- **doctor** — Run a read-only diagnosis for resource pressure, stopped containers, public ports, backup hygiene, notifications, and report baseline readiness
- **watch_check** — Run a one-shot restart check on watched targets and report restarts detected since the last check. Only docker targets can be inspected this way; systemd and pm2 targets are reported as skipped rather than assumed healthy
- **processes** — List the top processes by CPU or memory, with a total count and any zombies broken out separately
- **config_validate** — Check the config file this server is running on: which file was used, which rule selected it, what was read from each section, and anything wrong or silently ignored
- **watch_history** — List recorded restart incidents, newest first. Captured logs are excluded unless include_logs is set, because every incident carries a hundred lines of output twice over
- **watch_list** — List the targets being watched, with their kind and what the last check recorded
- **backup_create** — Create a Docker compose backup archive for all services or one service
- **backup_list** — List existing backup archives in the configured backup directory
- **backup_drill** — Verify a backup by booting an app in an isolated Docker environment and checking that it responds
- **backup_restore** — Restore Docker volumes from a backup archive. Destructive: confirm intent before calling.
- **install_list** — List available self-hosted apps that can be installed
- **install_app** — Install a self-hosted app via docker compose. Pre-checks docker, ports, and duplicates automatically.
- **install_status** — Check the status of an installed app
- **install_uninstall** — Stop an installed app and remove its containers. Data is preserved.
- **install_purge** — Stop an installed app and delete all data including containers, config, and volumes.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "homebutler": {
    "command": "npx",
    "args": ["-y","homebutler@latest"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/higangssh-homebutler/readme_