Homebox MCP server

homebox-mcp

<!-- mcp-name: io.github.dgahagan/homebox-mcp -->

An MCP server over the Homebox REST API, so an MCP client like Claude can work with your home inventory in plain language: "where is my impact driver", "what's in Tote B-3", "which warranties expire this year", "add this drill — here's a photo of the receipt and the model number". It answers questions, performs intake (create an item, attach the manual/receipt, tag and file it), manages attachments, and prints QR labels for totes and shelves — no hand-rolled curl.

Quickstart

You need a running Homebox instance (0.26+, see Requirements) and an API key from Profile → API Keys in the Homebox web UI.

Claude Code

claude mcp add homebox --scope user \
  -e HOMEBOX_URL=https://homebox.example.com \
  -e HOMEBOX_TOKEN=hb_xxxxxxxxxxxxxxxxxxxxxxxx \
  -- uvx homebox-mcp
claude mcp get homebox      # should show: Status ✔ Connected

--scope user makes it available from any project. uvx fetches and runs the published package in an ephemeral environment — nothing to install first.

Claude Desktop / generic MCP clients

Add to your client's MCP config (e.g. claudedesktopconfig.json):

{
  "mcpServers": {
    "homebox": {
      "command": "uvx",
      "args": ["homebox-mcp"],
      "env": {
        "HOMEBOX_URL": "https://homebox.example.com",
        "HOMEBOX_TOKEN": "hb_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

From a clone (no PyPI)

The module carries PEP 723 inline dependencies, so it also runs standalone with uv run --script — uv resolves mcp, httpx, pillow, and pillow-heif into an ephemeral venv on first run. Instead of env vars, drop credentials in a .env file next to the module:

git clone https://github.com/dgahagan/homebox-mcp
cd homebox-mcp
cp .env.example .env        # .env is gitignored
chmod 600 .env
# edit .env: HOMEBOX_URL + HOMEBOX_TOKEN

Then register the absolute path to the module (or to server.py, a compatibility shim kept for older registrations):

claude mcp add homebox --scope user -- \
  uv run --script /path/to/homebox-mcp/homebox_mcp.py

The server reads config from the environment, falling back to the sibling .env (resolved relative to the script, so the absolute-path invocation still finds it). The credential never enters the MCP config — it stays in the gitignored .env.

Requirements

sysadminsmedia fork at homebox.software. This server speaks the unified entities API introduced in 0.26. Older instances use a different API (/items, /locations, /labels) and are rejected on the first tool call with a clear error rather than failing cryptically.

• Homebox 0.26 or newer — the actively maintained

where you install homebox-mcp yourself.

• An API key — Homebox Profile → API Keys (the token starts with hb_).
• uv, or any Python ≥ 3.10 environment

isolated environment, so this needs no action. If you are installing into an environment already pinned to mcp<2, stay on homebox-mcp==1.0.1.

• MCP SDK 2.x (mcp>=2,<3), pulled in automatically. uvx/pipx build an

Configuration

All configuration is via environment variables (or the sibling .env for the clone workflow):

Shortened. The full README is on GitHub.