io.github.dgahagan/homebox-mcp

Attach a document to an item OR a location. `source` is a local file path or an http(s) URL (downloaded then uploaded). `doc_type` is e.g. manual, attachment, warranty, receipt, photo. `identifier` is assetId/alias/name for an item, or a location name/path (tried as a fallback if no item matches). Set `primary=True` to make a photo the entity's primary image — e.g. a "this is the spot" wayfinding photo on a shelf/tote location (doc_type="photo").

Look up a UPC/EAN barcode → name/manufacturer/model (optional path for boxed goods). Thin wrapper over GET /products/search-from-barcode.

Create an inventory item and enrich it in one call. `location` is a location name or /-separated path (must exist; use list_locations). `tags` are tag names (must already exist; use list_tags). `fields` maps custom-field name -> value; each value's JSON type picks the field type (string -> text, number -> number [integer-coerced], true/false -> boolean). Returns the new assetId and id.

Create a LOCATION entity (e.g. a new tote/bin/shelf) to bootstrap a new storage spot. `parent` is an existing location name or /-separated path (optional); `description` is optional free text, e.g. a contents summary (≤1000 chars). Returns the new location id. For deep paths, prefer import_csv's HB.location auto-create.

PERMANENTLY delete one attachment from an item or location (see list_attachments for ids). `confirm` must equal the attachment's exact title.

PERMANENTLY delete an item (assetId / alias field / exact name), including its attachments. `confirm` must equal the item's exact name. There is no undo.

PERMANENTLY delete a location (name or /-separated path). `confirm` must equal the location's exact name. A location that still contains items or sub-locations is refused unless `confirm_nonempty=True` — sub-locations are deleted with it, and its items are ORPHANED to the top level (not deleted). There is no undo.

PERMANENTLY delete one maintenance entry (see list_maintenance for ids). `confirm` must equal the entry's exact name.

PERMANENTLY delete a tag itself (it is removed from every tagged item; the items survive). `confirm` must equal the tag's exact name.

Duplicate an existing item (assetId / alias field / exact name), e.g. "I bought a second one". `prefix` is prepended to the new item's name. Copies custom fields by default; attachments and maintenance log only on request. NOTE: copied custom fields include the alias field verbatim — if you use one, give the copy its own value via set_fields right after. Returns the new item's id and assetId.

Export the whole inventory as a Homebox CSV (the complement of import_csv; also a quick backup). Saves to `save_to` (file path or directory; default: homebox-export.csv in the current directory) and returns the path and row count.

Return {field_value: assetId} for every entity that has the named custom field — a one-pass index for DEDUPE before a bulk import (q does not index custom fields, so this scans every entity). `field_name` defaults to $HOMEBOX_ALIAS_FIELD. assetId may be empty for un-asset'd rows. Deliberately uncapped: a truncated dedupe index causes duplicates, so expect a large result on a large inventory.

Finalize after a bulk photo attach: ensure every entity with photos has a primary image, then generate any missing thumbnails. (Wraps the set-primary-photos and create-missing-thumbnails actions, which are always run as a pair.)

Save a printable Homebox label PNG (QR + readable name) for a location or item, e.g. to stick on a tote/bin. `kind` is "location", "item", or "asset". For location/item, `identifier` is a name or slug (resolved to an id); for asset it's the assetId (e.g. 000-028). Saves to `out_dir` (default: $HOMEBOX_LABEL_DIR, else the current directory). Returns the saved file path.

Download one attachment (see list_attachments for ids) to a local path, so its content — e.g. an attached manual or receipt — can be read. `save_to` is a directory (keeps a name based on the title) or a full file path.

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) creates just the location. After import, call finalize_photos if you attached photos. Returns the count of data rows submitted.

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