homebutler

HomeButler is a single-binary CLI plus MCP server that lets you monitor servers, control Docker, wake machines, and scan your network — all from chat, AI tools, or the command line. The MCP server embedded in the Go binary is designed to be used by Claude Desktop, ChatGPT, Cursor, or any MCP client through JSON-RPC over stdio. You can also run a web dashboard or a terminal UI via the same binary. Use the MCP interface to issue status checks, inspect Docker containers, start wake-on-LAN devices, run port and network scans, and receive alert-driven diagnostics that AI agents can interpret.

To interact via MCP, connect your MCP client to the HomeButler binary’s stdio interface and issue tool calls (e.g., status, list-containers, wake, scan-ports). The JSON output is pipe-friendly and AI-friendly, enabling natural-language prompts from Claude/OpenClaw/OpenAI-style agents to orchestrate your homelab across multiple servers. In addition, you can run the embedded web dashboard with homebutler serve for a browser-based view, or use homebutler watch for a real-time TUI dashboard in the terminal.

Prerequisites:

• A supported OS (Linux, macOS, or Windows) with a Go toolchain or prebuilt binary available from releases.
• Optional: Docker if you plan to manage containers through the CLI, MCP, or web UI.

Install from prebuilt binary (recommended):

1. Download the latest release wheel/binary for your OS from the GitHub releases page.
2. Make it executable (Linux/macOS): chmod +x homebutler
3. Move it to a directory in your PATH, e.g. sudo mv homebutler /usr/local/bin/

Build from source (Go):

1. Ensure Go 1.20+ is installed: go version
2. Clone the repo: git clone https://github.com/Higangssh/homebutler.git
3. cd homebutler
4. go build -o homebutler ./...
5. Ensure the binary is in your PATH: mv homebutler /usr/local/bin/

Run MCP server and dashboards:

• Start MCP server (with MCP support): homebutler
• Start only MCP server (no UI): homebutler mcp
• Start web dashboard: homebutler serve
• Start TUI dashboard: homebutler watch

Notes:

• If you host behind a firewall, ensure port 8080 (default) or the port you specify for the web UI is allowed.
• The MCP server communicates via stdio when invoked as a process; configure your MCP client to connect accordingly.

Tips and common issues:

• The binary is a single self-contained executable with the CLI, MCP server, and web UI all built-in. No separate dependencies are required for the web UI when using the embedded go:embed frontend.
• For AI prompts to drive actions, rely on the MCP JSON-RPC output. Structure prompts to request status, docker actions, wake-on-LAN commands, or scans, and parse the returned JSON for results.
• If you plan multi-server orchestration via MCP, ensure SSH keys or credentials are configured in HomeButler’ s multi-server settings and that the target servers are reachable from the host.
• Environment variables (optional): HOMEBUTLER_NO_UI=1 can be used to run MCP logic without launching the UI components where a headless integration is desired.
• Web dashboard and TUI will reflect real-time status, including CPU, memory, disk, and open ports. Use the dashboard to quickly see alerts and jump into remediation steps via the MCP tools.
• When integrating with Claude Desktop, ChatGPT, Cursor, or other MCP clients, ensure your client’s output is JSON-RPC compatible and that you’re routing tool calls to the HomeButler MCP server endpoints.