Log inSubmit server
Homebutler logo

Homebutler

by Higangssh

Inspect and manage homelab servers, Proxmox guests, Docker containers, networks, alerts, and operational changes over MCP.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Homebutler

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "higangssh-homebutler": {
      "command": "npx",
      "args": [
        "-y",
        "homebutler@latest"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

The install command started, but didn't respond the way we expected when we tried to talk to it.

npx -y homebutler@latest

initialize succeeded but no response to tools/list.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 1mo ago.

Overview

Higangssh/homebutler MCP server exposes homelab operations through structured MCP tools for system status, Proxmox, Docker, networking, alerts, inventory, reports, and diagnostics. It runs as a single Go binary and can work across multiple servers through SSH, while returning readable summaries or machine-readable data rather than providing a general shell session. Use it when an agent needs to inspect infrastructure, identify changes since a previous snapshot, or perform narrowly targeted container and guest operations. The repository also describes CLI, JSON, web dashboard, and MCP usage, with no daemon or database required.

Use cases

  • Monitor CPU, memory, disk, uptime, and container health
  • Inspect Proxmox guests and track asynchronous tasks
  • Restart or stop explicitly targeted Docker containers
  • Discover network devices and identify port owners
  • Compare homelab snapshots and review operational changes

Key features

  • Proxmox cluster and guest inspection
  • Docker container management and diagnostics
  • System resource and process monitoring
  • Network scanning and open-port inspection
  • Snapshot-based reports and change detection
  • Inventory exports and read-only doctor checks

Tools40

What Homebutler lets your agent do. Expand a tool for its parameters.

Verified live~3.2k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

20/20 checks healthy over the last 79d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 8d ago via OSV.dev · homebutler@latest (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars308Stargazers on the source repository.
npm downloads230Package downloads in the last 30 days.
Last commit10d agoMost recent push to the default branch.
Install checkInconclusiveStarted but did not complete the MCP handshake in our test.
Tools exposed40Callable tools this server registers over MCP.
Directory activity6 viewsConfig copies, upvotes, and views on AllMCPs.

How Homebutler works

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

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Homebutler

Yes. It can list QEMU and LXC guests, inspect nodes and tasks, and start, reboot, or gracefully shut down one explicitly targeted guest after confirmation.

Yes. The MCP tools include Docker restart and stop operations by container name, along with listing, logs, statistics, process inspection, and container summaries.

Related MCP servers

All in Monitoring All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewHomebutler AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/higangssh-homebutler?style=directory)](https://allmcps.com/mcp/higangssh-homebutler)
HTML Embed
<a href="https://allmcps.com/mcp/higangssh-homebutler"><img src="https://allmcps.com/api/badge/higangssh-homebutler?style=directory" alt="Homebutler on AllMCPs" /></a>