# homebutler

Keeps a snapshot of your homelab server and reports what moved since the last look: containers, ports, disks, backups.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 305
- Author: Higangssh
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Higangssh/homebutler
- Updated: 2026-10-17
- HTML: https://affpapa.org/en/nevibecode/mcp/homebutler

## What it does

A single Go binary that takes a snapshot of a server and diffs it against the previous one. You get a short summary: what is healthy now, which warnings stand out, which items changed, and the commands to check them. Snapshots live in `~/.homebutler/reports/snapshots/`; old ones are pruned, the limit is set with `--keep`, and `--no-save` prints a preview without writing.

The point is that equal container counts prove nothing. Recreate a container under the same name and every number still matches while the workload underneath is different. Each change line therefore carries a kind (`gone`, `new`, `replaced`, `image`, `state`, `port`, `disk`, `skipped`), and `--json` exposes it as a field, so an agent branches on data instead of parsing prose.

The agent gets a narrow view of the server rather than a full shell. The binary has to sit on the machine being watched — without it there is nothing to compare. No daemon, no database.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add homebutler -- npx -y homebutler
```

### Codex

**Platform CLI**
```bash
codex mcp add homebutler -- npx -y homebutler
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "homebutler": {
            "command": "npx",
            "args": [
                "-y",
                "homebutler"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "homebutler": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "homebutler"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add homebutler npx -y homebutler
```

## When to use it
- spot a container recreated under the same name
- find which process took over a port
- read a server summary without dashboards
- check what changed after a compose redeploy
- give an assistant server state without shell access

## Example prompts
- Run a report on the server and tell me what changed since the last snapshot
- Which process listens on port 8080 now?
- Take a snapshot and keep only the last 7 reports

## Similar
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [Oh My Posh Validator](https://affpapa.org/en/nevibecode/mcp/oh-my-posh-validator.md) — MCP server · ★ 23643
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727
- [Coder](https://affpapa.org/en/nevibecode/mcp/coder.md) — MCP server · ★ 17160
- [mcp](https://affpapa.org/en/nevibecode/mcp/kubeshark-mcp.md) — MCP server · ★ 12109

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md