HomeButler CLI
A Go CLI that compares a server with its last snapshot, reports only changes that matter and serves them to an agent via MCP
- 312 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The write and destructive tools manage containers, backups and Proxmox guest power
- Access to servers goes through SSH keys, and logs and container configs may contain credentials
- The install commands deploy third-party apps on the server
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | shDetects OS and architecture. Alternative: brew install Higangssh/homebutler/homebutler. Then homebutler init to add servers.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The write and destructive tools manage containers, backups and Proxmox guest power
- Access to servers goes through SSH keys, and logs and container configs may contain credentials
- The install commands deploy third-party apps on the server
This is third-party code. Review the repository files before installing.
What it does
HomeButler remembers what your server looked like last time, and `homebutler report` tells you what changed and whether it matters. The first run creates a baseline in ~/.homebutler/reports/snapshots/, later runs compare with the latest snapshot, and old snapshots prune themselves (30 kept by default). Changes fall into eight kinds, and replaced is the most useful: a container was recreated under the same name, the counts did not move, yet HomeButler sees it. If nothing can be compared, for example Docker was down, it says so and does not announce that all is calm. Everyday homelab tools sit alongside. `homebutler status` shows CPU, memory and disk, and `homebutler inventory scan` maps containers, ports and topology. `homebutler doctor` looks for a full disk, ports open on every interface and forgotten backups. `homebutler watch` saves logs before and after a Docker, systemd or PM2 crash and works out the cause, and `homebutler backup drill` boots an archive in an isolated container and checks that it starts. One command installs popular apps such as Uptime Kuma, Jellyfin and Pi-hole. There is no daemon and no database: nothing runs on the machines it watches, and several servers can be managed over SSH. Output comes both readable and as JSON. The built-in MCP server gives an agent narrow structured access instead of a shell with full SSH.
Who it is for. For owners of home servers and small Docker, Proxmox and Raspberry Pi setups who want a summary of changes instead of graphs.
Good fit when
- You want a morning summary of a server: what disappeared, what appeared and which port is now answered by a different service
- You want to verify that a backup truly restores and add `homebutler backup drill` to the same cron as the backup
- A container crashes at night and you need logs from before and after the restart with a cause analysis, be it OOM or panic
- An agent needs read-only access to the state of several servers
- You need to deploy a self-hosted app such as Uptime Kuma or Pi-hole quickly without writing a compose file by hand
Not a fit when
- You need real-time load graphs: Beszel or Netdata fit better, while HomeButler answers what changed
- You need constant availability checks with notifications: Uptime Kuma does that, and HomeButler can only install it
- You need a browser log viewer across all containers: the project points to Dozzle for that
- A fleet of hundreds of servers is run by Kubernetes: the tool is built for home and small setups
Example request
Run `homebutler report` and tell me what changed on the server since the last snapshot and what to check firstLimitations
Comparison runs from snapshot to snapshot, so the first report run creates only a baseline. If Docker was down when either snapshot was taken, HomeButler skips the container comparison and marks it skipped.
Read mode in MCP stops changes but not reading: the docker_logs and docker_inspect tools can show credentials someone printed into logs. The network_scan tool pings every address on the local subnet to fill the ARP table. In read mode the report always runs with the no_save parameter.
How to disable. Remove the homebutler entry from your MCP config and restart the client. For background watching run `homebutler watch uninstall`. The binary is removed with `brew uninstall homebutler` or by deleting the file, and snapshots live in ~/.homebutler/.
FAQ
How do I connect HomeButler to Claude Code?
Add a homebutler server to .mcp.json with the npx command and the arguments -y and homebutler@latest. If the binary is installed, use the homebutler command with the argument mcp. Then restart the client.
How do I stop an agent from changing anything on the server?
Start MCP with `--max-risk read`. Every tool has a class: read, write or destructive. Tools above the ceiling disappear from the list, and the server refuses a direct call. By default everything is offered.
What does replaced mean in the report?
The name is the same but the thing under it is different. A typical case is `docker compose up -d`, which recreates a container: the count of containers stays the same, and a counts-based report would say nothing significant changed.
Can I try HomeButler without real servers?
Yes. `homebutler mcp --demo` starts the MCP server in demo mode, so you can test the agent connection without access to any machines.
Do I need to install anything on the watched servers?
No. No agent, daemon or database runs on them. The binary runs on the controlling machine and reaches servers over SSH, and the web dashboard starts on demand with `homebutler serve`.
Discussion
No questions or reviews yet.
Related
CLI toolsMCP server for managing Docker in natural language: containers, images, networks and volumes, including remote hosts over SSH
A single-container web dashboard for monitoring and controlling a fleet of 1C MCP servers: status, indexing progress, VRAM and license checks
A Node.js manager for MCP servers: it starts local servers, connects remote ones and gives a client one address, with a REST API for control
MCP server for Proxmox VE: manage VMs, LXC, snapshots and backups from an agent with permission control and command approval
An MCP server for Linux diagnostics: an AI client reads services, logs and network on local and remote hosts, read-only
BetterDB MCP
BetterDB Monitor
BetterDB MCP server: the agent reads Valkey and Redis metrics, slow commands, hot keys and anomalies and investigates incidents from stored history
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| HomeButler (this entry) | no | 312 | ||
| AgentDock | no | API key | 1,285 | a secure MCP runtime for an agent operating local machines, servers and containers |
| Docker MCP server | no | not required | 749 | manages Docker containers, images and volumes in natural language, with no snapshots or change summaries |
| SSH MCP Server (classfang): remote commands over SSH | no | not required | 988 | runs commands and handles files over SSH and offers no narrow set of maintenance tools |
README in short
The core idea is that an owner cares only about meaningful changes. A table explains each change kind in the report, and the other sections cover verified backups, app installs and Proxmox.