homebox-mcp

# homebox-mcp

<!-- mcp-name: io.github.dgahagan/homebox-mcp -->

[![PyPI version](https://img.shields.io/pypi/v/homebox-mcp)](https://pypi.org/project/homebox-mcp/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/dgahagan/homebox-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/dgahagan/homebox-mcp/actions/workflows/ci.yml)

An [MCP](https://modelcontextprotocol.io) server over the
[Homebox](https://homebox.software) 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](#requirements))
and an API key from **Profile → API Keys** in the Homebox web UI.

### Claude Code

```bash
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`):

```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](https://peps.python.org/pep-0723/) 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:

```bash
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):

```bash
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](https://github.com/sysadminsmedia/homebox) at
  [homebox.software](https://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.10** 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):

| Variable | Required | Purpose |
|----------|----------|---------|
| `HOMEBOX_URL` | yes | Base URL of your Homebox instance (no trailing slash). |
| `HOMEBOX_TOKEN` | yes | Homebox API key (`hb_…`). |
| `HOMEBOX_ALIAS_FIELD` | no | Name of one custom field to treat as a stable item identifier — items can be resolved by it, summaries surface it, and `field_index` defaults to it. Unset = resolve by assetId/name only. See [Conventions](#conventions-optional). |
| `HOMEBOX_LABEL_DIR` | no | Where `generate_label` / `qrcode` save output. Default: current working directory. |

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

| Tool | Purpose |
|------|---------|
| `search_items(query?, tags?, limit=20)` | Search items by keyword and/or tag names (AND of both); returns each with assetId, location, and the alias field. |
| `get_item(identifier)` | Full detail for one item: location path, identity, purchase, warranty, custom fields, tags, attachments. |
| `list_locations()` | The full location tree as an indented outline. |
| `location_contents(location, recursive=False)` | Items directly in a location plus its sub-location names; `recursive=True` walks the whole subtree and returns every nested item with its full location path. |
| `list_tags(detail=False)` | All tag (label) names; `detail=True` returns full objects (description, color, icon, parent tag). |
| `warranties_expiring(before?, after?, lifetime=False)` | Items whose warranty expires in `after…before` (`after` defaults to today, excluding already-expired); `lifetime=True` lists lifetime-warranty items. |

### Create & intake

| Tool | Purpose |
|------|---------|
| `create_item(name, location?, quantity=1, manufacturer?, model?, serial?, purchase_price?, purchase_date?, purchase_from?, warranty_expires?, notes?, fields?, tags?)` | Create and enrich an item in one call. `fields` is a dict typed by JSON value (string→text, number→number [integer-coerced], bool→boolean); `tags` must already exist. Returns the new assetId. |
| `import_csv(csv_text)` | Bulk-create items and locations from a Homebox CSV in one multipart request. `HB.location` **auto-creates** the path hierarchy; recognizes `HB.name`, `HB.tags`, `HB.quantity`, `HB.serial_number`, `HB.model_number`, `HB.manufacturer`, `HB.notes`, `HB.purchase_*`, `HB.warranty_expires`, `HB.field.<name>`. |
| `create_location(name, parent?, description?)` | Create a location (tote/bin/shelf) to bootstrap a new storage spot; `description` doubles as a contents manifest. |
| `barcode_lookup(code)` | UPC/EAN → name/manufacturer/model (optional, for boxed goods). |
| `duplicate_item(identifier, copy_attachments=False, copy_custom_fields=True, copy_maintenance=False, prefix="Copy of ")` | Duplicate an item ("I bought a second one"). Copied custom fields include the alias field verbatim — give the copy its own value after. |

### 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](#how-it-works-and-homebox-026-gotchas)).

| Tool | Purpose |
|------|---------|
| `set_item(identifier, new_name?, description?, notes?, quantity?, purchase_price?, purchase_date?, purchase_from?, insured?, archived?, fields?)` | General item editor: rename, notes, quantity, purchase info, insured/archived flags, custom fields. Quantity-only edits use a partial PATCH. |
| `move_item(identifier, location)` | Move an item to another location (partial PATCH — nothing else changes). |
| `set_warranty(identifier, expires?, lifetime?, details?)` | Set warranty end date, lifetime flag, and terms summary. |
| `set_identity(identifier, manufacturer?, model_number?, serial_number?)` | Set manufacturer / model / serial (e.g. after a nameplate photo reveals them). |
| `set_fields(identifier, fields)` | Create or overwrite custom fields (upsert; typed by JSON value type). |
| `set_tags(identifier, tags, mode="add")` | Add / remove / replace tags on an item; unknown tag names are auto-created (partial PATCH). |
| `set_tag(name, new_name?, description?, color?, icon?, parent?, clear_parent=False)` | Edit **a tag's own** metadata (rename, color, icon, parent tag for grouping) — not what's tagged on an item. Creates the tag if new. |
| `set_location(location, new_name?, parent?, clear_parent?, description?, notes?, tags?, tags_mode?, entity_type?, asset_id?, fields?)` | General location editor: rename, move (or `clear_parent` to root), tags, notes, entity type, assetId, custom fields. |
| `mark_sold(identifier, sold_price?, sold_to?, sold_date?, sold_notes?, clear=False)` | Record a sale (price/buyer/date/notes) or `clear=True` to un-sell; pair with `set_item(archived=True)` to retire the item. |

### Maintenance log

| Tool | Purpose |
|------|---------|
| `log_maintenance(identifier, name, description?, completed_date?, scheduled_date?, cost?)` | Add an entry — "changed the mower oil today" (completed) or "sharpen blades in spring" (scheduled). |
| `list_maintenance(identifier?, status="both")` | Entries for one item, or across the whole inventory ("what maintenance is due?"); `status` = scheduled / completed / both. |
| `set_maintenance(entry_id, ...)` | Edit an entry — e.g. mark a scheduled one completed by setting `completed_date`. |
| `delete_maintenance(entry_id, confirm)` | Delete one entry (`confirm` = its exact name). |

### Reporting

| Tool | Purpose |
|------|---------|
| `inventory_stats(by="totals", start?, end?)` | Totals (counts, total value, warranty count), value by location or tag, or purchase-price over time — the cheap way to answer "what's my inventory worth?". |
| `export_csv(save_to?)` | Export the whole inventory as a Homebox CSV (complement of `import_csv`; quick backup). |
| `list_custom_fields(field?)` | Discover t