Homebox MCP

Get full detail for one item by assetId (e.g. 000-028), alias custom field, or name (fuzzy fallback: first keyword match). Includes location path, serial, model, purchase, warranty, custom fields, tags, and attachments.

Bulk-create items and locations from a Homebox CSV (multipart import). This is the bulk creator for the photo-intake pipeline — one request imports everything, avoiding ~4 API calls per item. Recognized columns: HB.name, HB.location (path e.g. "Garage/Loft" — AUTO-CREATES the hierarchy), HB.tags (must already exist; see list_tags), HB.quantity, HB.serial_number, HB.model_number, HB.manufacturer, HB.notes, HB.purchase_price, HB.purchase_from, HB.purchase_time, HB.warranty_expires, HB.field.<name> (custom fields). A location-only row (HB.location set, contents described elsewhere) cre…

Inventory statistics — the cheap way to answer "what's my inventory worth?" without scanning items. `by` is: totals — counts (items/locations/tags/users), total purchase price, items with warranty; locations — total value per location; tags — total value per tag; purchase-price — value over time (optional YYYY-MM-DD start/end).

List an item's (or location's) attachments with their ids — the handle needed by get_attachment / rename_attachment / delete_attachment. `identifier` is assetId / alias field / name, or a location name/path.

Discover the custom-field schema actually in use: with no arg, all custom-field NAMES across the inventory; with `field`, the distinct VALUES of that field ({"total", "values"}, capped at `limit`). Useful before set_fields/field_index on an unfamiliar instance.

Return the full location tree as an indented outline.

List maintenance entries — for one item (assetId / alias field / name) or, with no identifier, across the whole inventory ("what maintenance is due?"). `status` is "scheduled" (upcoming), "completed", or "both".

List all tag (label) names. Set `detail=True` to instead return full tag objects (name, description, color, icon, parent tag name) for auditing tag setup — pair with set_tag to edit any of these.

List what is in a location (e.g. a tote or shelf), by location name. Returns the items directly in that location plus any sub-locations (their names only — not their contents). Set `recursive=True` to instead walk the whole subtree and return every item nested under it, each tagged with its full location path; use this when a location (e.g. Garage, Basement) has sub-locations you also want the contents of, to avoid querying each one by hand. `location` is a name or /-separated path (for duplicate names).

Add a maintenance-log entry to an item (assetId / alias field / exact name) — e.g. "changed the mower oil today" (completed_date) or "sharpen blades in spring" (scheduled_date). Dates are YYYY-MM-DD; `cost` is a number. Returns the new entry's id.

Record that an item was sold (assetId / alias field / exact name): price, buyer, YYYY-MM-DD date, notes — only the args you pass are set. `clear=True` instead erases all four sold fields (un-sells the item). Other fields are preserved. Pair with set_item(archived=True) if the item should also leave active inventory.

Move an item to another location (assetId / alias field / exact name). `location` is a location name or /-separated path (see list_locations). Uses a partial PATCH, so nothing else on the item changes.

Save a raw QR-code JPEG encoding arbitrary `data` (e.g. a deep link). For tote labels prefer generate_label (adds the readable name). Saves to `out_dir` (default: $HOMEBOX_LABEL_DIR, else the current directory). Returns the saved file path.

Update an attachment's title, type (manual/attachment/warranty/receipt/ photo), or primary flag (see list_attachments for ids). Only the args you pass change; the rest is re-sent as-is.

Search inventory items by name/keyword and/or by tag names (AND of both when both given — e.g. everything tagged "power-tool"). Returns items (not locations) with their immediate location, assetId, and the alias custom field (if $HOMEBOX_ALIAS_FIELD is configured). Use get_item for full detail on one result.

Create or update custom fields on an existing item (assetId / alias field / exact name). `fields` maps custom-field name -> value; each value's JSON type picks the field type (string -> text, number -> number [integer-coerced — the API 500s on float number values], true/false -> boolean). Upsert semantics: named fields are created or overwritten; other fields are preserved.

Set manufacturer/model/serial on an existing item (assetId / alias field / exact name). Only the args you pass change; other fields are preserved. Use when a nameplate/label photo reveals a serial number or a model-number correction after the item was created.

General item editor (assetId / alias field / exact name): rename, edit description/notes/quantity, purchase info, insured/archived flags, and custom fields in one call. Only the args you pass are changed. Quantity-only changes go via a partial PATCH; anything else uses a full-body PUT that preserves the rest of the item (the 0.26 PUT-clears gotcha). `fields` maps custom-field name -> value, typed by JSON type (see set_fields). To move an item use move_item; for warranty/identity/tags see set_warranty/set_identity/set_tags.

Edit a LOCATION's metadata (find it by current name or /-path): rename, `description` (e.g. a contents manifest), notes, tags, custom fields (values typed by JSON type). Only the args you pass change; other fields are preserved. `parent` moves it under another location; `clear_parent=True` moves it to the root. `entity_type` (e.g. "Item") converts a mis-created entity — rare. `asset_id` overrides the auto-assigned assetId.

Edit a maintenance entry (see list_maintenance for ids) — e.g. mark a scheduled entry completed by setting completed_date. Only the args you pass change; the rest of the entry is re-sent as-is (the update is a full PUT).

Create or edit a tag's own metadata — NOT what's tagged on an item (see set_tags for that). Matches `name` case-insensitively against list_tags; creates the tag if it doesn't exist yet. Only the args you pass are changed. `parent` nests this tag under another (existing) tag name, for grouping related tags in the Homebox UI (e.g. several condition-* tags under a "condition" parent); pass `clear_parent=True` to un-nest it. Use list_tags(detail=True) to see current tag metadata first.

Add, remove, or replace tags on an existing item (assetId / alias field / exact name). `mode` is "add" (default — merges with the item's existing tags), "remove" (drops just the named tags, keeps the rest), or "replace" (item ends up with exactly these tags, nothing else). Tag names are matched case-insensitively against list_tags and auto-created if they don't exist yet. Everything else on the item is untouched (partial PATCH).

Set warranty info on an existing item (assetId / alias field / exact name). `expires` is a YYYY-MM-DD date (warranty end), `lifetime` flags a lifetime warranty, `details` is a short terms summary (e.g. "limited lifetime, test/measurement instruments excluded"). Only the args you pass change; other fields are preserved.

List items whose warranty expires in a date window, or items with a lifetime warranty. `before`/`after` are ISO dates (YYYY-MM-DD): returns items with after <= warrantyExpires <= before. `after` defaults to TODAY, so already-expired warranties are excluded unless you pass an earlier `after`. Set `lifetime=True` to instead list items flagged as lifetime warranty (`before`/`after` ignored). Useful for "which warranties expire this year".