homebox-mcp — Claude Code MCP server: install
Connects Homebox to an MCP client for plain-language inventory searches, item intake, location lookup, and warranty checks.
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-mcpWhat homebox-mcp 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.
What it helps with
- 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 for the agent
- Find my impact driver in Homebox and tell me where it is.
- Add a drill to
Garage/Shelf 1with its manufacturer and model. - Show the items whose warranties expire after today.
How to install homebox-mcp
Platform CLI
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-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from homebox-mcp <command>
Platform CLI
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-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from homebox-mcp <command>
Config file
{
"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>
Config file
{
"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>
Platform CLI
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-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from homebox-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about homebox-mcp
How do I install homebox-mcp in Claude Code?
Run claude mcp add homebox-mcp -e HOMEBOX_URL=<HOMEBOX_URL> -e HOMEBOX_TOKEN=<HOMEBOX_TOKEN> -- uvx homebox-mcp.
What does homebox-mcp do?
It lets an MCP client query and update a Homebox inventory using natural-language requests. Its tools cover items, locations, tags, warranties, attachments, CSV intake, and QR labels.
Which Homebox version is required?
Use Homebox 0.26 or newer and an API key from Profile → API Keys. Earlier releases use a different API and are rejected when the first tool is called.
