Homebox Server

License

MCP (Model Context Protocol) server for managing Homebox inventory via AI assistants.

🇧🇷 Versão em Português

Prerequisites

This addon was designed to work with Homebox running on Home Assistant.

Recommended Homebox addon: homebox-ingress-ha-addon

To install Homebox:

1. Add the repository: https://github.com/Oddiesea/homebox-ingress-ha-addon
2. Install the Homebox addon
3. Start and configure your inventory

About

This addon exposes an MCP server that allows AI assistants (like Claude) to interact with your Homebox inventory. You can:

• 📦 List, create, and manage items
• 📍 Organize hierarchical locations
• 🏷️ Categorize with labels
• 🔍 Search items by name or description
• 📊 Get inventory statistics

Installation

Add Repository

1. In Home Assistant, go to Settings → Add-ons → Add-on Store
2. Click the menu (⋮) → Repositories
3. Add: https://github.com/oangelo/homebox-mcp
4. Click Add → Close

Install Add-on

1. Search for "Homebox MCP Server" in the store
2. Click Install
3. Configure the Homebox credentials
4. Start the add-on

Configuration

homebox_url: "http://homeassistant.local:7745"
homebox_token: "YOUR_HOMEBOX_API_TOKEN"
mcp_auth_enabled: false
mcp_auth_token: ""
log_level: "info"

Creating the Homebox API Token

1. Access Homebox
2. Go to Profile (user icon)
3. Click API Tokens
4. Click Create Token
5. Copy the generated token

External Access via Cloudflare Tunnel

To use with Claude.ai web or access externally, we recommend using the Cloudflared addon to create a secure tunnel.

Configure Cloudflared

1. Install the Cloudflared addon
2. Configure the tunnel to expose port 8099:

additional_hosts:
  - hostname: mcp.yourdomain.com
    service: http://homeassistant:8099

3. Use the URL in Claude.ai: https://mcp.yourdomain.com/sse

Local Access

On the local network, access directly:

http://homeassistant.local:8099/sse

MCP Authentication (Optional)

The addon supports optional Bearer token authentication to protect the MCP endpoint.

Configure Token

1. Access the addon web page (click "Homebox MCP" in the sidebar)
2. Click the "🎲 Generate Token" button
3. Click "📋 Copy"
4. In the addon settings:
   • Enable mcp_auth_enabled
   • Paste the token in mcp_auth_token
   • Click Save

Configure in Claude.ai

Field	Value
Server URL	https://your-domain.com/sse
OAuth Client ID	mcp (or any text)
OAuth Client Secret	Paste the token generated in the addon

Using with Claude

Claude.ai Web (Experimental)

1. Access the MCP settings in Claude.ai
2. Add the URL: https://mcp.yourdomain.com/sse
3. Configure OAuth as shown above (optional but recommended)

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "homebox": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.yourdomain.com/sse"]
    }
  }
}

Interaction Examples

You: List all items in the garage
Claude: [Lists items filtered by location]

You: Add a "Bosch Drill" to the tools cabinet
Claude: [Creates item in the specified location]

You: Where is my camera?
Claude: [Searches and returns item location]

MCP Tools

Tool	Description
homebox_list_locations	List all locations
homebox_list_items	List items with filters
homebox_search	Search for items
homebox_create_item	Create new item
homebox_move_item	Move item
homebox_list_labels	List labels
homebox_get_statistics	Get statistics

Full Documentation

Local Development

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export HOMEBOX_URL="http://localhost:7745"
export HOMEBOX_TOKEN="your-api-token"

# Run server
cd homebox-mcp/app
python server.py

# Test with MCP Inspector
npx @anthropic/mcp-inspector http://localhost:8099/sse

License

MIT License - see LICENSE.md