Homebox MCP
Lets an MCP client search and update a self-hosted Homebox home inventory
- Pricing
- Open source
- Platforms
- CLI, self-hosted, Linux
- Runs
- Locally
- Version
- 1.5.1
- Listing updated
- today
Similar MCP servers
About Homebox MCP
Homebox MCP is an open-source MCP server for productivity. It runs locally on your machine and is started by your AI client.
This server connects an assistant to your own Homebox instance, version 0.26 or later, through its API key. You can ask where an item is, what is in a tote, or which warranties expire this year, and the server answers from your inventory.
Reads accept loose identifiers such as asset ID, a custom alias field, or a name. Writes require an exact identifier, so a typo or ambiguous match is refused rather than changing the wrong item. Locations can be given as paths like Garage/Shelf 1. Intake covers creating items with purchase and warranty details, bulk CSV import, duplicating items and attaching manuals or receipts, and it can print QR labels for totes and shelves.
It runs locally over stdio from PyPI with uvx, and releases carry signed provenance attestations.
Install
Run in a terminal
claude mcp add homebox-mcp --env HOMEBOX_URL='<HOMEBOX_URL>' --env HOMEBOX_TOKEN='<HOMEBOX_TOKEN>' -- uvx homebox-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"homebox-mcp": {
"command": "uvx",
"args": [
"homebox-mcp"
],
"env": {
"HOMEBOX_URL": "<HOMEBOX_URL>",
"HOMEBOX_TOKEN": "<HOMEBOX_TOKEN>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"homebox-mcp": {
"command": "uvx",
"args": [
"homebox-mcp"
],
"env": {
"HOMEBOX_URL": "<HOMEBOX_URL>",
"HOMEBOX_TOKEN": "<HOMEBOX_TOKEN>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"homebox-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"homebox-mcp"
],
"env": {
"HOMEBOX_URL": "<HOMEBOX_URL>",
"HOMEBOX_TOKEN": "<HOMEBOX_TOKEN>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"homebox-mcp": {
"command": "uvx",
"args": [
"homebox-mcp"
],
"env": {
"HOMEBOX_URL": "<HOMEBOX_URL>",
"HOMEBOX_TOKEN": "<HOMEBOX_TOKEN>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"homebox-mcp": {
"command": "uvx",
"args": [
"homebox-mcp"
],
"env": {
"HOMEBOX_URL": "<HOMEBOX_URL>",
"HOMEBOX_TOKEN": "<HOMEBOX_TOKEN>"
}
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
HOMEBOX_URLBase URL of your Homebox instance (>= 0.26), e.g. https://homebox.example.comRequiredHOMEBOX_TOKENHomebox API key (Profile -> API Keys, starts with hb_)RequiredHOMEBOX_ALIAS_FIELDOptional: name of one custom field treated as a stable item identifier for lookupsHOMEBOX_LABEL_DIROptional: directory where label/QR PNGs are saved (default: current directory)
Tools this server provides (11)
Taken from the project documentation; the running server may differ.
- search_items
- Searches items by keyword, tags and location.
- get_item
- Returns full detail for one item.
- list_locations
- Shows the location tree as an outline.
- location_contents
- Lists items in a location, optionally recursively.
- list_tags
- Lists tag names or full tag objects.
- warranties_expiring
- Lists items whose warranty expires in a range.
- create_item
- Creates and enriches an item in one call.
- import_csv
- Bulk-creates items and locations from a Homebox CSV.
- create_location
- Creates a location such as a tote, bin or shelf.
- barcode_lookup
- Looks up a UPC or EAN code.
- duplicate_item
- Duplicates an item.
What it does
- Inventory search
- Searches by keyword, tag and location, including sub-locations.
- Warranty tracking
- Lists items whose warranties expire in a date range, or have lifetime cover.
- Item intake
- Creates items with manufacturer, model, serial, purchase and warranty fields.
- Bulk CSV import
- Creates items and builds the location hierarchy from a Homebox CSV.
- QR labels
- Generates label and QR images for totes and shelves.
- Safe writes
- Refuses ambiguous identifiers on write tools instead of guessing.
Good for
- Find where a tool is stored
- List warranties expiring this year
- Add a purchase from a receipt photo
- Print QR labels for storage bins
- Import a spreadsheet of belongings
Pricing
Open source
Open-source Python package; requires a Homebox instance
Homebox MCP FAQ
Which Homebox version is needed?
0.26 or newer, the sysadminsmedia fork. Older instances use a different API and are rejected with an error.
What credentials does it need?
HOMEBOX_URL and a Homebox API key beginning with hb_, created under Profile then API Keys.
How is it installed?
Add it to your MCP client with uvx homebox-mcp, or run it from a clone with uv.
How many tools are there?
About 39.
Is Homebox MCP free?
Yes. Homebox MCP is open source, so you can use and self-host it for free.
How do I add Homebox MCP to Claude Code?
Run this command in your terminal: claude mcp add homebox-mcp --env HOMEBOX_URL='<HOMEBOX_URL>' --env HOMEBOX_TOKEN='<HOMEBOX_TOKEN>' -- uvx homebox-mcp
What are the best alternatives to Homebox MCP?
The closest alternatives to Homebox MCP are Ha MCP, Concord MCP, Midplane, note1 and Todoist.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.
