# Homebox MCP

> Homebox MCP is an open-source MCP server for productivity. Lets an MCP client search and update a self-hosted Homebox home inventory. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, Linux, macOS, Windows
- **Repository:** https://github.com/dgahagan/homebox-mcp
- **MCP Registry name:** io.github.dgahagan/homebox-mcp
- **Categories:** [productivity](https://ai-powered.com/categories/productivity), [databases](https://ai-powered.com/categories/databases)
- **Listing updated:** 2026-11-18

## About

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.

## Features

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

## Install

### Claude Code (Terminal)

```sh
claude mcp add homebox-mcp --env HOMEBOX_URL='<HOMEBOX_URL>' --env HOMEBOX_TOKEN='<HOMEBOX_TOKEN>' -- uvx homebox-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "homebox-mcp": {
      "command": "uvx",
      "args": [
        "homebox-mcp"
      ],
      "env": {
        "HOMEBOX_URL": "<HOMEBOX_URL>",
        "HOMEBOX_TOKEN": "<HOMEBOX_TOKEN>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "homebox-mcp": {
      "command": "uvx",
      "args": [
        "homebox-mcp"
      ],
      "env": {
        "HOMEBOX_URL": "<HOMEBOX_URL>",
        "HOMEBOX_TOKEN": "<HOMEBOX_TOKEN>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "homebox-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "homebox-mcp"
      ],
      "env": {
        "HOMEBOX_URL": "<HOMEBOX_URL>",
        "HOMEBOX_TOKEN": "<HOMEBOX_TOKEN>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "homebox-mcp": {
      "command": "uvx",
      "args": [
        "homebox-mcp"
      ],
      "env": {
        "HOMEBOX_URL": "<HOMEBOX_URL>",
        "HOMEBOX_TOKEN": "<HOMEBOX_TOKEN>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "homebox-mcp": {
      "command": "uvx",
      "args": [
        "homebox-mcp"
      ],
      "env": {
        "HOMEBOX_URL": "<HOMEBOX_URL>",
        "HOMEBOX_TOKEN": "<HOMEBOX_TOKEN>"
      }
    }
  }
}
```

## Tools

- `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.

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

## Alternatives

- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.
- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [Todoist](https://ai-powered.com/mcp/todoist): Todoist is a freemium MCP server for productivity.
- [Google_calendar](https://ai-powered.com/mcp/google-calendar-3): Google_calendar is a freemium MCP server for productivity.
- [Jira](https://ai-powered.com/mcp/jira): Jira is a freemium MCP server for productivity.
- [Google Workspace MCP Server](https://ai-powered.com/mcp/google-workspace-mcp-server-2): Google Workspace MCP Server is an open-source MCP server for productivity.

---
Source: https://ai-powered.com/mcp/homebox-mcp
