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.

Related MCP server: homekit-cli

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, or any Python ≥ 3.10 environment where you install homebox-mcp yourself.

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

Labels & finalize

How it works (and Homebox 0.26 gotchas)

The value of this server is as much in what it works around as in what it exposes. These are hard-won behaviors of the 0.26 entities API:

• Items and locations are unified "entities" (/v1/entities); a location is an entity whose entity-type has isLocation=true. A new item with no entityTypeId lazily gets a default Item type.

• GET /entities returns non-location entities only. Location children never appear in /entities results, even with parentIds — sub-locations come from the entity tree (/entities/tree). location_contents merges both sources, and delete_location's emptiness check counts items and sub-locations.

• Deleting a non-empty location cascades sub-locations but orphans items. Force-deleting a location (confirm_nonempty=True) deletes its sub-locations with it, but its items survive, re-parented to the top level. Move items out first if you don't want them loose.

• List/search responses are lightweight summaries — they omit fields and have an empty assetId. The server fetches full detail (GET /entities/{id}) before returning assetId/alias, so search_items/get_item are accurate.

• q does not index custom fields. Resolving by an alias-field value uses a scan fallback (one detail fetch per item). Resolving by assetId (via /v1/assets/{id}) or name is cheaper — prefer assetId when you have it (e.g. the value create_item returns).

• PUT clears omitted fields, including assetId. Every write tool rebuilds a full body from a fresh GET (_preserve_item_body) and overrides only the targeted keys. create_item assigns the asset ID after enrichment so it survives.

• Attachment titles are basenamed on /. Homebox treats a title as path-like, so "front 3/4 view" silently stores as "4 view". The server sanitizes /→- in attach titles.

• Number custom fields are integer-typed. A float numberValue (e.g. 17000.0, which FastMCP produces from a float-typed arg) makes the API 500 "Unknown Error". The server coerces number values to int; pass whole numbers.

• Custom-field values are type-keyed (textValue / numberValue / booleanValue). The server rebuilds each field by its declared type — coercing everything to textValue (an earlier bug) silently wiped numeric/boolean fields on any PUT.

• Pagination. Entity listings over one page (200) were silently truncated; the server pages through to the reported total, so search, dedupe, and warranty sweeps stay correct on large inventories.

Conventions (optional)

Homebox's built-in assetId is a stable numeric handle, but it isn't something you'd type from memory. If you want a human-meaningful stable identifier — useful for cross-referencing items with receipts, spreadsheets, or another system — add a custom field (say item_id) holding a slug like makita-xdt131 and point HOMEBOX_ALIAS_FIELD at it. Then:

• items resolve by that slug in every read and write tool,

• search_items/get_item summaries surface it, and

• field_index() defaults to it, giving you a one-call dedupe map before a bulk import.

This is entirely optional — leave HOMEBOX_ALIAS_FIELD unset and items resolve by assetId or name only. Nothing about the field name is special; any single custom field works.

Companion scripts

Two standalone helper scripts ship in the repo (not MCP tools):

• annotate_location_photos.py turns one wide photo of a shelf bank into one boxed/labeled image per shelf (--rows N), and can upload each straight to its Homebox location with --upload. See its --help.

• heic2jpg.py converts HEIC/HEIF (iPhone photos) to JPEG for ad-hoc use (./heic2jpg.py FILE...). Note the attach tools already auto-convert HEIC on upload, so this is only needed to feed HEIC frames to a vision step before upload.

Both rely on pillow-heif, which bundles libheif — there's no system package to install.

Security

• API key handling. In the clone workflow the key lives in .env, which is gitignored and should be mode 600 (chmod 600 .env). Never commit it. In the uvx workflow it's passed through your MCP client's config — treat that file as a secret too.

• Key rotation. Rotating the Homebox HBOX_AUTH_API_KEY_PEPPER invalidates every issued key — mint a new one and update your config.

• Confirm-gated deletes. All four delete tools require confirm to equal the target's exact name and carry the MCP destructiveHint annotation, so a well-behaved client prompts before any destructive call.

• Use HTTPS for any remote Homebox instance — the API key is sent on every request in the Authorization header.

Development

git clone https://github.com/dgahagan/homebox-mcp
cd homebox-mcp

# Run the test suite (httpx mocked with respx — no live instance needed)
uv run --with pytest --with respx --with . pytest

# Lint
uv run --with ruff ruff check .

The server is a single module (homebox_mcp.py) with PEP 723 inline dependencies. See CONTRIBUTING.md for setup and PR expectations, and CHANGELOG.md for release notes.

License

MIT © Dan Gahagan