Homebox MCP

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

• Homebox 0.26 or newer — the actively maintained 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.
• An API key — Homebox Profile → API Keys (the token starts with hb_).
• [`uv`](https://docs.astral.sh/uv/), or any Python ≥ 3.11 environment where you install homebox-mcp yourself.
• MCP SDK 2.x (mcp>=2,<3), pulled in automatically. uvx/pipx build an 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.

Configuration

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

Tools

~39 tools. Reads accept a fuzzy identifier (assetId, alias field, exact name, then first keyword match). Write tools require an exact identifier (assetId, alias field, or exact name) — a typo or an ambiguous match is refused rather than mutating the wrong item. An assetId must be in the full 000-012 form: a bare 12 is matched as a name or alias, never as asset 000-012. Locations are referenced by name or /-separated path (e.g. Garage/Shelf 1) to disambiguate duplicate names.

Read / Q&A

Create & intake

Edit

All write tools resolve by exact identifier and preserve everything you don't touch (a full-body PUT that echoes the rest of the item back — see gotchas).

Maintenance log

Reporting

Attachments

Uploads auto-convert HEIC/HEIF (iPhone photos) to JPEG so Homebox always

stores a browser-renderable image, and sanitize / in titles (Homebox treats

a title as a path and would otherwise truncate it).

Deletes (confirm-gated)

Every delete requires confirm to equal the target's exact name and carries the MCP destructiveHint annotation, so clients prompt before running them.

| delete_item(identifier, confirm) | Permanently delete an item and its attachments. No und