Homebox MCP Server

A Model Context Protocol (MCP) server for interacting with Homebox, a self-hosted inventory management system.

Source Project: Homebox | Documentation

Overview

This MCP server enables AI assistants (like Claude or LM Studio) to interact with your Homebox instance using natural language. You can manage your inventory, create items, update locations, search for items, and more.

Want to use this with local AI? Check out our Local AI Stack Example for detailed setup instructions using LM Studio + Qwen 3 8B or other local LLMs with function calling support.

Features

• Item Management

  • List all inventory items with filtering and pagination
  • Get detailed information about specific items
  • Create new inventory items
  • Update existing items (including parent-child relationships)
  • Delete items
  • Search items by query
  • Parent-child item relationships (e.g., items stored inside other items)
  • Automatic web links for all items and parent items

• Location Management

  • List all storage locations
  • Create new locations (with support for nested/hierarchical locations)
  • Automatic web links for all locations

• Label Management

  • List all labels/tags
  • Create new labels with custom colors

• Flexible URL Configuration

  • Separate LAN and WAN URL support
  • Automatic URL generation for items, locations, and labels
  • Switch between local and public URLs based on your network context
  • All API calls use efficient LAN access, web links adapt to your needs

Prerequisites

• Node.js 18+ or later
• A running Homebox instance
• Either a Homebox API key (recommended) OR username and password

Installation

Option 1: Install from npm (Recommended)

The easiest way to get started is to install the package directly from npm:

npm install -g homebox-mcp

Note: This is currently a proof-of-concept/work in progress. Features may change and improvements are ongoing.

Updating

To update to the latest version from npm:

Linux/macOS:

./update.sh

Windows:

update.bat

Or manually:

npm update -g homebox-mcp

Option 2: Install from Source

1. Clone this repository:

git clone https://github.com/danielrosehill/Homebox-MCP-1125.git
cd Homebox-MCP-1125

2. Install dependencies:

npm install

3. Build the server:

npm run build

Configuration

The MCP server supports flexible URL configuration for both LAN and WAN access:

Environment Variables

• HOMEBOX_LOCAL_URL - LAN URL for your Homebox instance (e.g., http://10.0.0.4:7745)
• HOMEBOX_WAN_URL - (Optional) WAN/public URL for external access (e.g., https://homebox.yourdomain.com)
• USE_LAN_API - (Optional) Use LAN for API calls (default: true). Set to false to use WAN for API
• LAN_LINKS - (Optional) Use LAN for display links (default: false). Set to true to force LAN links

Authentication (choose one):

• HOMEBOX_API_KEY - (Recommended) Persistent API key from Homebox. If provided, username/password are ignored.
• HOMEBOX_USERNAME - Your Homebox username (email) - only needed if not using API key
• HOMEBOX_PASSWORD - Your Homebox password - only needed if not using API key

Note: If both HOMEBOX_API_KEY and username/password are provided, the API key takes precedence. API keys are recommended as they don't require token refresh and provide more reliable authentication.

URL Selection Logic:

For API calls:

• By default, uses LAN (USE_LAN_API=true) for faster performance
• Set USE_LAN_API=false to use WAN for API calls

For web links:

• By default, uses WAN if available (LAN_LINKS=false)
• If WAN URL is not set, falls back to LAN
• Set LAN_LINKS=true to force LAN links even when WAN is available

How It Works:

• API calls default to LAN for speed (configurable with USE_LAN_API)
• Web links default to WAN for shareability (configurable with LAN_LINKS)
• This gives you full control over which URL is used for each purpose

Note: When using username/password authentication, the MCP server automatically handles login and token refresh. When using an API key, no token refresh is needed.

Screenshots For POC

LM Studio

Asset search:

Env variable configuration:

Env variables for LAN and WAN instance URLs:

MCP tools (LM Studio, Qwen 3)

Retrieve asset URL from asset ID:

---

Streamlit

---

Claude Code

Configure by adding array with env variables to .mcp.json (note the trailing dot)

---

MCP Configuration

Using npm Package (Recommended)

With API Key (Recommended)

{
  "mcpServers": {
    "homebox": {
      "command": "npx",
      "args": ["homebox-mcp"],
      "env": {
        "HOMEBOX_LOCAL_URL": "http://10.0.0.4:7745",
        "HOMEBOX_API_KEY": "your_api_key_here"
      }
    }
  }
}

With Username/Password (LAN Only)

{
  "mcpServers": {
    "homebox": {
      "command": "npx",
      "args": ["homebox-mcp"],
      "env": {
        "HOMEBOX_LOCAL_URL": "http://10.0.0.4:7745",
        "HOMEBOX_USERNAME": "your_email@example.com",
        "HOMEBOX_PASSWORD": "your_password"
      }
    }
  }
}

Alternative: Using Global Install

If you installed globally with npm install -g homebox-mcp:

{
  "mcpServers": {
    "homebox": {
      "command": "homebox-mcp",
      "env": {
        "HOMEBOX_LOCAL_URL": "http://10.0.0.4:7745",
        "HOMEBOX_API_KEY": "your_api_key_here"
      }
    }
  }
}

Or with username/password:

{
  "mcpServers": {
    "homebox": {
      "command": "homebox-mcp",
      "env": {
        "HOMEBOX_LOCAL_URL": "http://10.0.0.4:7745",
        "HOMEBOX_USERNAME": "your_email@example.com",
        "HOMEBOX_PASSWORD": "your_password"
      }
    }
  }
}

Using Source Installation

If you cloned the repository and built from source:

{
  "mcpServers": {
    "homebox": {
      "command": "node",
      "args": ["/path/to/Homebox-MCP-1125/dist/index.js"],
      "env": {
        "HOMEBOX_LOCAL_URL": "http://10.0.0.4:7745",
        "HOMEBOX_USERNAME": "your_email@example.com",
        "HOMEBOX_PASSWORD": "your_password"
      }
    }
  }
}

WAN Links (automatic when WAN URL is provided)

Given that Homebox is a home inventory system, using the LAN for API calls is preferred where available. Many folks also use WAN URLs to bind to stickers/NFC tags so that they can be read when not on the LAN.

For that reason, env parameters for both WAN and LAN URLs are provided, along with booleans for the preferred URL construction pattern for asset links.

This provides flexibility and accommodates users who want LAN for API but WAN for link presentation:

Using npx (Recommended)

{
  "mcpServers": {
    "homebox": {
      "command": "npx",
      "args": ["homebox-mcp"],
      "env": {
        "HOMEBOX_LOCAL_URL": "http://10.0.0.4:7745",
        "HOMEBOX_WAN_URL": "https://homebox.yourdomain.com",
        "HOMEBOX_USERNAME": "your_email@example.com",
        "HOMEBOX_PASSWORD": "your_password"
      }
    }
  }
}

Force LAN Links (even with WAN URL configured)

{
  "mcpServers": {
    "homebox": {
      "command": "npx",
      "args": ["homebox-mcp"],
      "env": {
        "HOMEBOX_LOCAL_URL": "http://10.0.0.4:7745",
        "HOMEBOX_WAN_URL": "https://homebox.yourdomain.com",
        "LAN_LINKS": "true",
        "HOMEBOX_USERNAME": "your_email@example.com",
        "HOMEBOX_PASSWORD": "your_password"
      }
    }
  }
}

Use WAN for API (not recommended - slower)

{
  "mcpServers": {
    "homebox": {
      "command": "npx",
      "args": ["homebox-mcp"],
      "env": {
        "HOMEBOX_LOCAL_URL": "http://10.0.0.4:7745",
        "HOMEBOX_WAN_URL": "https://homebox.yourdomain.com",
        "USE_LAN_API": "false",
        "HOMEBOX_USERNAME": "your_email@example.com",
        "HOMEBOX_PASSWORD": "your_password"
      }
    }
  }
}

For LM Studio

1. Open LM Studio
2. Go to Settings → MCP Servers
3. Add a new server with the following configuration:
   • Name: Homebox
   • Command: npx (or homebox-mcp if globally installed)
   • Args: homebox-mcp (if using npx; leave empty if using global install)
   • Environment Variables:
     • HOMEBOX_LOCAL_URL: http://10.0.0.4:7745
     • HOMEBOX_WAN_URL: https://homebox.yourdomain.com (optional, leave empty for LAN-only)
     • USE_LAN_API: true (optional, default: true - use LAN for API calls)
     • LAN_LINKS: false (optional, default: false - use WAN for links when available)
     • Authentication (choose one):
       • HOMEBOX_API_KEY: your_api_key_here (recommended)
       • OR both HOMEBOX_USERNAME and HOMEBOX_PASSWORD

For Other MCP Clients

Use the following configuration as a reference:

{
  "mcpServers": {
    "homebox": {
      "command": "npx",
      "args": ["homebox-mcp"],
      "env": {
        "HOMEBOX_LOCAL_URL": "http://10.0.0.4:7745",
        "HOMEBOX_WAN_URL": "https://homebox.yourdomain.com",
        "HOMEBOX_API_KEY": "your_api_key_here"
      }
    }
  }
}

Note: When both HOMEBOX_LOCAL_URL and HOMEBOX_WAN_URL are provided, the server automatically uses WAN URLs for web links. Set LAN_LINKS=true to force LAN links instead.

Usage Examples

Once configured, you can interact with your Homebox inventory using natural language:

Listing Items

"Show me all my inventory items" "List items in my garage location"

Getting Item Links

"Get the link for asset 003-168" "Get the link for asset 5451" "What's the link to my Thai cookbook?" "Get me the link for the bag of cables"

The server automatically uses Homebox's # prefix for asset ID searches, so queries like "5451" or "003-539" will find exact asset ID matches.

The server will return a direct clickable link like:

 DIRECT LINK: http://10.0.0.4:7745/item/cd8dee2f-9f5b-4f10-a05b-c952c1deafc5

Searching

"Find all items related to networking" "Search for items with 'laptop' in the name"

Creating Items

"Create a new item called 'Dell Monitor' in my office location" "Add a new inventory item: Samsung SSD 1TB, model 870 EVO, serial number ABC123" "Create a new item called 'USB Cable' inside the electronics box" (requires parent item ID)

Updating Items

"Update the quantity of item [ID] to 5" "Change the location of my laptop to the office"

Parent-Child Item Relationships

"Set the parent of [item ID] to [parent item ID]" "Move this item into that box" (requires item IDs) "Remove the parent from [item ID]" "Take this item out of its container"

Custom Fields

"Add a text field called 'ISBN' with value '978-0-123456-78-9' to item [ID]" "Add a number field called 'Weight' with value 2.5 to item [ID]" "Add a boolean field called 'Fragile' with value true to item [ID]" "Remove the field 'ISBN' from item [ID]"

Managing Locations

"List all my storage locations" "Create a new location called 'Workshop' under 'Garage'"

Managing Labels

"Show me all my labels" "Create a new label called 'Electronics' with color #0000FF"

Local AI Setup

Example config:

• Local AI Stack Setup Guide - Complete setup for LM Studio + Qwen 3 8B
• Client Configuration Examples - Configurations for Continue.dev, Cline, Ollama, and more
• System Prompt for AI Models - Recommended system prompt for AI assistants that includes API fallback instructions

Available Tools

Items

• list_items - List inventory items with optional filtering
• get_item - Get detailed information about a specific item
• get_item_link - Get direct link to an item by asset ID, name, or description (recommended for getting links!)
• create_item - Create a new inventory item
• update_item - Update an existing item
• delete_item - Delete an item
• search_items - Search for items using a query string
• set_item_parent - Set or change the parent item for an item (creates parent-child relationship)
• remove_item_parent - Remove the parent relationship from an item
• add_item_field - Add or update a custom field on an item (supports text, number, boolean, time types)
• remove_item_field - Remove a custom field from an item

Locations

• list_locations - List all storage locations
• create_location - Create a new location

Labels

• list_labels - List all labels/tags
• create_label - Create a new label

Development

Running in Development Mode

npm run dev

Building

npm run build

Running the Built Version

npm start

Example:

When you search for "003-168":
- The MCP server finds the item with assetId "003-168"
- Homebox returns both the assetId AND the UUID
- The URL is built using the UUID: http://10.0.0.4:7745/item/cd8dee2f-9f5b-4f10-a05b-c952c1deafc5

Database Schema: For detailed database schema information and ERD diagrams, see the docs/db-schema/ directory which includes both PDF and PNG exports of the full schema and items-specific schema.

License

MIT

Author

Daniel Rosehill