Homebox MCP Server - Home Assistant Add-on

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

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

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