RELATED 01
ProxmoxMCP-Plus
Run day-to-day Proxmox VE work, from VMs and LXCs to snapshots, backups and ISOs, from an MCP client
644GitHub stars
10k/moPyPI downloads
70popularity score
homebutler
Homelab operations over MCP: change reports, Docker, backups, app installs and Proxmox guests
By SangheeSon (individual) Go Local · stdio DevOps and monitoring
57 popularity score ★ 315 ↓ 397/wk
Connect your client
Local (npm)
Add in one click
Opens the app, which asks before it adds the server.
Or add it by command or config
Claude CodeTerminal
claude mcp add homebutler -- npx -y homebutler@latestClaude Desktopclaude_desktop_config.json
{
"mcpServers": {
"homebutler": {
"command": "npx",
"args": [
"-y",
"homebutler@latest"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"homebutler": {
"command": "npx",
"args": [
"-y",
"homebutler@latest"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"homebutler": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"homebutler@latest"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.homebutler]
command = "npx"
args = ["-y", "homebutler@latest"]Gemini CLITerminal
gemini mcp add --scope user homebutler npx -- -y homebutler@latestLocal (from source)
Add in one click
Opens the app, which asks before it adds the server.
Or add it by command or config
FirstTerminal
go install github.com/Higangssh/homebutler@latestClaude CodeTerminal
claude mcp add homebutler -- homebutler mcpClaude Desktopclaude_desktop_config.json
{
"mcpServers": {
"homebutler": {
"command": "homebutler",
"args": [
"mcp"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"homebutler": {
"command": "homebutler",
"args": [
"mcp"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"homebutler": {
"type": "stdio",
"command": "homebutler",
"args": [
"mcp"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.homebutler]
command = "homebutler"
args = ["mcp"]Gemini CLITerminal
gemini mcp add --scope user homebutler homebutler -- mcpSettings 1
--max-risk |
Optional: Command-line flag after `mcp` (or after the npx package name): highest tool class offered, read, write or destructive. |
|---|
What it does
homebutler is one Go binary that bundles a command line, a web dashboard and an MCP server for a home server, all built on the same code. The MCP part talks JSON-RPC over stdio and hands back typed results, so nobody has to open a shell on the box for it. Most people start with `report`. It saves a snapshot of the machine and compares it with the one before, tagging each difference with one of eight kinds (gone, new, replaced, image, state, port, disk, skipped). A container recreated under the same name shows up as replaced even when the count did not move. When a comparison could not be made, it is marked skipped instead of passing as all clear.
Beyond that there are tools for load and processes, open ports and LAN discovery. Docker containers can be listed, inspected, restarted or stopped, and their logs read. Restarts can be watched, with an incident history kept. Compose backups come with a drill that boots an archive in an isolated container and checks it answers HTTP. It also installs apps from a built-in catalogue using generated compose files, and reads Proxmox VE nodes, guests and tasks. Most tools take an optional `server` argument, which runs them over SSH on a machine named in the config.
At v1.3.0, internal/capability/capability.go registers 44 tools and tags each by risk: 27 read, 13 write, 4 destructive. The tool table in the MCP docs has 40 of them and misses `watch_add`, `watch_remove`, `notify_test` and `alerts_history`. The `mcp` command takes a `--max-risk` ceiling. Tools above it drop out of the list and are refused if called by name anyway. It defaults to destructive, which offers everything. Under `--max-risk read`, `report` stays available but never saves a snapshot, whatever the caller sends (cmd/mcp.go). Add `--demo` for made-up data that touches no real machine.
What it needs
| Runtime | Node.js 16+ |
|---|---|
| Runs on | macOS, Windows, Linux |
| Also |
|
Node.js 16 or later for the npx route. On first install the npm package downloads a prebuilt binary from GitHub releases for Linux, macOS or Windows on x64 or arm64, so it needs internet access then. Remote servers need SSH set up in ~/.config/homebutler/config.yaml (`homebutler init` walks you through it), with the binary copied there by `homebutler deploy`. Proxmox needs an API token in the config, plus a second action token for guest power actions. The source route needs Go 1.25 or later.
Limits
- Not covered Runs over stdio only. There is no HTTP transport for the MCP server.
- Not covered No tools for accepting SSH host keys, deploying or upgrading, or running the dashboard or watcher daemon. Those stay on the CLI.
- Read only Every tool is offered by default. Start with `--max-risk read` (or `write`) to hide and refuse the tools above that class.
- Read only Read mode stops changes, not reads: `docker_logs` and `watch_history` with `include_logs` can return whatever an app printed, credentials included.
- Limit `network_scan` pings every address on the local subnet, and the Proxmox reads call the Proxmox API, even in read mode.
- Limit Proxmox guest power tools need `confirm: true` plus a separate action token in the config.
- Limit `proxmox_script_command` returns a pinned `curl | bash` line for a Community Script and never runs it.
- Limit `install_purge` deletes an app's config and volumes and takes no backup first.
- Limit Restart history is only recorded while a watcher runs. `watch_add` writes the list but starts nothing.
- Limit The npm page shows `npx -y homebutler-mcp`, an older separate package (0.7.3). The repository's `npx -y homebutler@latest` is current.
MCP runs over stdio only, with no HTTP transport. By design there are no tools for accepting SSH host keys, deploying to or upgrading remote hosts, or running the dashboard or watcher daemon; those stay on the CLI. Proxmox guest power tools need literal `confirm: true` and a separate action token. `proxmox_script_command` prints a pinned script command but never runs it. `backup_restore` refuses bind mounts named in an archive. Restart history is only recorded while a watcher runs. The npm package's README shows `npx -y homebutler-mcp`, which is an older separate package (0.7.3); the repository's `npx -y homebutler@latest` is current.
Who it suits
A good fit if you run a homelab of Docker hosts, perhaps with Proxmox, and want an assistant to tell you what changed since last time and handle routine jobs such as restarts, backups and app installs without an open SSH shell. It runs on your own machine and needs no account. If you only want the assistant to look, start it with `--max-risk read` and the tools that stop containers, purge apps or restore volumes are neither offered nor callable. Look elsewhere for cloud infrastructure, Kubernetes, or a server a hosted assistant reaches over HTTP, since it only speaks stdio.
Tools 44
27 only read, 13 change things, 4 can delete or overwrite. A ? marks an optional parameter.
proxmox_status- Proxmox VE version, cluster state and resources
endpoint?: string proxmox_guests- List QEMU and LXC guests, with optional filters
endpoint?: stringnode?: stringstatus?: stringtype?: string proxmox_node- Details of one node
endpoint?: stringnode: string proxmox_tasks- Recent tasks on a node
endpoint?: stringnode: string system_status- CPU, memory, disk and uptime
server?: string proxmox_guest_startchanges- Start a guest; needs confirm: true
endpoint: stringnode: stringtype: enumvmid: integerconfirm: boolean proxmox_guest_rebootchanges- Reboot a guest; needs confirm: true
endpoint: stringnode: stringtype: enumvmid: integerconfirm: boolean proxmox_guest_shutdowndeletes- Clean shutdown of a guest; needs confirm: true
endpoint: stringnode: stringtype: enumvmid: integerconfirm: boolean proxmox_task_status- Status of one task by UPID
endpoint: stringnode: stringupid: string proxmox_script_list- List the pinned Proxmox VE Community Scripts catalogue
proxmox_script_command- Print the install command for one Community Script without running it
slug: string docker_list- List containers
server?: string docker_restartchanges- Restart a container
name: stringserver?: string docker_stopdeletes- Stop a container
name: stringserver?: string docker_logs- Fetch a container's log output
name: stringlines?: integerserver?: string docker_stats- Resource usage of running containers
server?: string docker_top- Processes in a container, read from the host
name: stringserver?: string docker_inspect- Image, state, ports, mounts and health of a container, without env values
name: stringserver?: string wakechanges- Send a Wake-on-LAN packet to a configured device
target: stringbroadcast?: string open_ports- Listening ports with their owning processes
server?: string network_scan- Find devices on the local network
alerts- Check resource usage against the configured thresholds
server?: string inventory_scan- Map system, containers, app ports and system ports
server?: string inventory_export- Export the inventory as Mermaid or JSON
format?: stringserver?: string reportchanges- Health summary that compares a new snapshot with the last one and labels each change by kind
keep?: integerno_save?: booleanserver?: string doctor- Read-only diagnosis of disk, memory, stopped containers, public ports, backups, notifications and config
backup_max_age_hours?: integerserver?: string watch_checkchanges- One-off check of watched targets for restarts
server?: string processes- Top processes by CPU or memory, with zombies listed apart
limit?: integersort_by?: stringserver?: string config_validate- Check the config file this server is using
strict?: boolean watch_history- Restart incidents, newest first, logs optional
limit?: integercontainer?: stringinclude_logs?: booleanserver?: string watch_list- Show watched targets and their last recorded state
server?: string watch_addchanges- Add a target to the watch list
container: stringkind?: enumunit?: stringserver?: string watch_removechanges- Drop a target from the watch list, keeping its incidents
container: stringserver?: string notify_testchanges- Send a real test message through every configured notification channel
server?: string alerts_history- Recorded alert and remediation entries
server?: string backup_createchanges- Write a backup archive of compose services and volumes
service?: stringto?: stringserver?: string backup_list- List backup archives in the backup directory
server?: string backup_drillchanges- Boot an archive in an isolated container and check it answers
app?: stringall?: booleanarchive?: stringserver?: string backup_restoredeletes- Overwrite Docker volumes with data from an archive
archive: stringservice?: stringserver?: string install_list- List the built-in catalogue of self-hosted apps
install_appchanges- Install a catalogue app with a generated compose file
app: stringport?: integer install_status- Status of an app homebutler installed
app: string install_uninstallchanges- Stop an installed app and remove its containers, keeping data
app: string install_purgedeletes- Remove an installed app with its config and volumes
app: string