io.github.dgahaganPublished by GitHub account dgahaganv1.3.0Updated Nov 2, 2026
Homebox home inventory: search, intake, warranties, attachments, locations, tags, QR labels
Connects an assistant to a self-hosted Homebox home inventory: search items, do intake, track warranties and maintenance, manage attachments, and print QR…
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
[PyPI version] [License: MIT] [CI]
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.
You need a running Homebox instance (0.26+, see Requirements) and an API key from Profile → API Keys in the Homebox web UI.
--scope user makes it available from any project. uvx fetches and runs the
published package in an ephemeral environment — nothing to install first.
Add to your client's MCP config (e.g. claude_desktop_config.json):
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:
Then register the absolute path to the module (or to server.py, a
compatibility shim kept for older registrations):
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.
/items, /locations, /labels) and are rejected on the first tool call
with a clear error rather than failing cryptically.hb_).uv, or any Python ≥ 3.11 environment
where you install homebox-mcp yourself.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.All configuration is via environment variables (or the sibling .env for the
clone workflow):
~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.
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).
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).
Every delete requires confirm to equal the target's exact name and carries
the MCP destructiveHint annotation, so clients prompt before running them.
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:
/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.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.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).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./. Homebox treats a title as
path-like, so "front 3/4 view" silently stores as "4 view". The server
sanitizes /→- in attach titles.numberValue (e.g.
17000.0, which the MCP SDK produces from a float-typed arg) makes the API
500 "Unknown Error". The server coerces number values to int; pass whole
numbers.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.total, so search, dedupe, and
warranty sweeps stay correct on large inventories.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:
search_items/get_item summaries surface it, andfield_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.
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.
.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.HBOX_AUTH_API_KEY_PEPPER invalidates
every issued key — mint a new one and update your config.confirm to equal the
target's exact name and carry the MCP destructiveHint annotation, so a
well-behaved client prompts before any destructive call.Authorization header.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.
MIT © Dan Gahagan
Source: README.md at commit 9047913
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.
tagslimitqueryGet 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.
identifierrequiredReturn the full location tree as an indented outline.
Takes no parameters.
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).
locationrequiredmax_itemsrecursiveList 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.
detailList 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".
afterbeforelifetimeCreate 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.
namerequiredtagsmodelnotesfieldsseriallocationquantitymanufacturerpurchase_datepurchase_frompurchase_price+1 moreAttach 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").
titlerequiredsourcerequiredprimarydoc_typeidentifierrequiredList 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.
identifierrequiredDownload 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.
save_torequiredidentifierrequiredattachment_idrequiredUpdate 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.
titleprimarydoc_typeidentifierrequiredattachment_idrequiredBulk-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.
csv_textrequiredCreate 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.
namerequiredparentdescriptionEdit 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.
tagsnotesfieldsparentasset_idlocationrequirednew_nametags_modedescriptionentity_typeclear_parentSet 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.
detailsexpireslifetimeidentifierrequiredCreate 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.
fieldsrequiredidentifierrequiredSet 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.
identifierrequiredmanufacturermodel_numberserial_numberMove an item into a location or into another item (assetId / alias field / exact name). `location` is the destination's name or /-separated path — a location (see list_locations) or a container item, e.g. a lens into 'Camera Bag' or 'Office/Camera Bag' — or a container item's assetId ('000-012'). A location wins over an item with the same name; reach the item with a longer path or its assetId. A name that matches more than one location, or more than one item, is refused. Uses a partial PATCH, so nothing else on the item changes.
locationrequiredidentifierrequiredGeneral 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.
notesfieldsinsuredarchivednew_namequantityidentifierrequireddescriptionpurchase_datepurchase_frompurchase_priceRecord 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.
clearsold_tosold_dateidentifierrequiredsold_notessold_priceDuplicate 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.
prefixidentifierrequiredcopy_attachmentscopy_maintenancecopy_custom_fieldsAdd, 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).
modetagsrequiredidentifierrequiredCreate 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.
iconnamerequiredcolorparentnew_namedescriptionclear_parentPERMANENTLY delete an item (assetId / alias field / exact name), including its attachments. `confirm` must equal the item's exact name. There is no undo.
confirmrequiredidentifierrequiredPERMANENTLY 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.
confirmrequiredlocationrequiredconfirm_nonemptyPERMANENTLY delete a tag itself (it is removed from every tagged item; the items survive). `confirm` must equal the tag's exact name.
namerequiredconfirmrequiredPERMANENTLY delete one attachment from an item or location (see list_attachments for ids). `confirm` must equal the attachment's exact title.
confirmrequiredidentifierrequiredattachment_idrequiredSave 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.
kindout_diridentifierrequiredSave 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.
datarequiredout_dirReturn {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.
field_nameFinalize 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.)
Takes no parameters.
Look up a UPC/EAN barcode → name/manufacturer/model (optional path for boxed goods). Thin wrapper over GET /products/search-from-barcode.
coderequiredAdd 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.
costnamerequiredidentifierrequireddescriptioncompleted_datescheduled_dateList 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".
statusidentifierEdit 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).
costnameentry_idrequireddescriptioncompleted_datescheduled_datePERMANENTLY delete one maintenance entry (see list_maintenance for ids). `confirm` must equal the entry's exact name.
confirmrequiredentry_idrequiredInventory 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).
byendstartExport 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.
save_toDiscover 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.
fieldlimit90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
claude mcp add homebox --scope user \ -e HOMEBOX_URL=https://homebox.example.com \ -e HOMEBOX_TOKEN=hb_xxxxxxxxxxxxxxxxxxxxxxxx \ -- uvx homebox-mcpclaude mcp get homebox # should show: Status ✔ Connected{ "mcpServers": { "homebox": { "command": "uvx", "args": ["homebox-mcp"], "env": { "HOMEBOX_URL": "https://homebox.example.com", "HOMEBOX_TOKEN": "hb_xxxxxxxxxxxxxxxxxxxxxxxx" } } }}git clone https://github.com/dgahagan/homebox-mcpcd homebox-mcpcp .env.example .env # .env is gitignoredchmod 600 .env# edit .env: HOMEBOX_URL + HOMEBOX_TOKENclaude mcp add homebox --scope user -- \ uv run --script /path/to/homebox-mcp/homebox_mcp.pygit clone https://github.com/dgahagan/homebox-mcpcd homebox-mcp
# Run the test suite (httpx mocked with respx — no live instance needed)uv run --with pytest --with respx --with . pytest
# Lintuv run --with ruff ruff check .