# homebox-mcp

Connects Homebox to an MCP client for plain-language inventory searches, item intake, location lookup, and warranty checks.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 16
- Author: dgahagan
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/dgahagan/homebox-mcp
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/mcp/homebox-mcp

## What it does

homebox-mcp exposes the Homebox REST API through MCP. An agent can search items and tags, inspect the storage tree, list nested contents, check warranty dates, and create inventory records. It also supports CSV import, location creation, UPC/EAN lookup, attachments, and QR label output for containers and shelves.

Read operations accept fuzzy identifiers, while changes require an exact assetId, alias value, or item name. A path such as `Garage/Shelf 1` helps distinguish locations with the same name. The `uvx` setup passes `HOMEBOX_URL` and `HOMEBOX_TOKEN`; `HOMEBOX_ALIAS_FIELD` and `HOMEBOX_LABEL_DIR` provide optional configuration.

You need Homebox 0.26 or newer and an API key from Profile → API Keys. Older Homebox releases use a different API, so this server rejects them on the first tool call rather than applying an update to the wrong endpoint.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `HOMEBOX_URL`, `HOMEBOX_TOKEN`, `HOMEBOX_ALIAS_FIELD`, `HOMEBOX_LABEL_DIR` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env HOMEBOX_URL=<HOMEBOX_URL> --env HOMEBOX_TOKEN=<HOMEBOX_TOKEN> --env HOMEBOX_ALIAS_FIELD=<HOMEBOX_ALIAS_FIELD> --env HOMEBOX_LABEL_DIR=<HOMEBOX_LABEL_DIR> --transport stdio homebox-mcp -- uvx homebox-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from homebox-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add homebox-mcp --env HOMEBOX_URL=<HOMEBOX_URL> --env HOMEBOX_TOKEN=<HOMEBOX_TOKEN> --env HOMEBOX_ALIAS_FIELD=<HOMEBOX_ALIAS_FIELD> --env HOMEBOX_LABEL_DIR=<HOMEBOX_LABEL_DIR> -- uvx homebox-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from homebox-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "homebox-mcp": {
            "command": "uvx",
            "args": [
                "homebox-mcp"
            ],
            "env": {
                "HOMEBOX_URL": "<HOMEBOX_URL>",
                "HOMEBOX_TOKEN": "<HOMEBOX_TOKEN>",
                "HOMEBOX_ALIAS_FIELD": "<HOMEBOX_ALIAS_FIELD>",
                "HOMEBOX_LABEL_DIR": "<HOMEBOX_LABEL_DIR>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from homebox-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "homebox-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "homebox-mcp"
            ],
            "env": {
                "HOMEBOX_URL": "<HOMEBOX_URL>",
                "HOMEBOX_TOKEN": "<HOMEBOX_TOKEN>",
                "HOMEBOX_ALIAS_FIELD": "<HOMEBOX_ALIAS_FIELD>",
                "HOMEBOX_LABEL_DIR": "<HOMEBOX_LABEL_DIR>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from homebox-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e HOMEBOX_URL=<HOMEBOX_URL> -e HOMEBOX_TOKEN=<HOMEBOX_TOKEN> -e HOMEBOX_ALIAS_FIELD=<HOMEBOX_ALIAS_FIELD> -e HOMEBOX_LABEL_DIR=<HOMEBOX_LABEL_DIR> homebox-mcp uvx homebox-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from homebox-mcp <command>

## When to use it
- find stored items by name, tag, or identifier
- check which warranties expire in a date range
- create inventory entries with purchase and warranty details
- bulk-import items and locations from CSV
- inspect contents across nested storage locations

## Example prompts
- Find my impact driver in Homebox and tell me where it is.
- Add a drill to `Garage/Shelf 1` with its manufacturer and model.
- Show the items whose warranties expire after today.

## Similar
- [retail-expert](https://affpapa.org/en/nevibecode/skills/retail-expert.md) — skill · 526 installs
- [mcp-vtex](https://affpapa.org/en/nevibecode/mcp/mcp-vtex.md) — MCP server · ★ 274
- [mcp-tiny](https://affpapa.org/en/nevibecode/mcp/mcp-tiny.md) — MCP server · ★ 274
- [ezpzfile](https://affpapa.org/en/nevibecode/mcp/ezpzfile.md) — MCP server · ★ 5
- [Amazon Seller](https://affpapa.org/en/nevibecode/skills/amazon-seller.md) — skill · 5300 installs
- [shopify-automation](https://affpapa.org/en/nevibecode/skills/shopify-automation.md) — skill · 4800 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md