Skip to main content
Glama
Homebox MCP Server

Homebox MCP Server

by Supermaxman

Homebox MCP Server

npm version npm downloads License: MIT Work in Progress

alt text

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.

Related MCP server: Homebox MCP Server

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

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
  1. Install dependencies:

npm install
  1. 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

alt text

Env variable configuration:

alt text

Env variables for LAN and WAN instance URLs:

alt text

MCP tools (LM Studio, Qwen 3)

alt text

Retrieve asset URL from asset ID:

alt text


Streamlit

alt text

alt text


Claude Code

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

alt text

alt text

alt text


MCP Configuration

{
  "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"
      }
    }
  }
}

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:

{
  "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"
      }
    }
  }
}
{
  "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"
      }
    }
  }
}
{
  "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"

"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:

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

Available Tools

21 tools
add_item_attachmentA

Add an attachment (image, document, etc.) to an inventory item. The file_location can be either a URL (http:// or https://) to fetch the file from, or an absolute file path on the local filesystem (e.g., '/mnt/images/photo.png'). The filename is automatically extracted from the URL or path. Supported file types include images (jpg, png, gif, webp), documents (pdf, doc, docx), and other common formats.

Inputs: id (required), file_location (required).

add_item_fieldA

Add or update a custom field on an item. Custom fields can store additional metadata like ISBN, serial numbers, or any other custom data. Supports text, number, boolean, and time field types.

Inputs: itemId (required), fieldName (required), fieldType (required), value (required).

create_itemB

Create a new inventory item in Homebox

Inputs: name (required), description, locationId, parentId, +8 more.

create_labelC

Create a new label/tag

Inputs: name (required), description, color.

create_locationC

Create a new storage location

Inputs: name (required), description, parentId.

delete_itemB

Delete an inventory item by ID

Inputs: id (required).

get_itemA

Get detailed information about a specific inventory item by ID

Inputs: id (required).

get_locationA

Get detailed information about a specific location by ID, including its children and parent.

Inputs: id (required).

get_locations_treeA

Get the hierarchical tree structure of all locations in Homebox. Shows parent-child relationships between locations.

Inputs: no named parameters.

list_itemsC

List inventory items from Homebox. Supports filtering by page number and location.

Inputs: page, pageSize, locations, labels, +1 more.

list_labelsA

List all labels/tags in Homebox

Inputs: no named parameters.

list_locationsA

List all storage locations in Homebox

Inputs: no named parameters.

remove_item_fieldB

Remove a custom field from an item by field name.

Inputs: itemId (required), fieldName (required).

remove_item_parentA

Remove the parent relationship from an item. This makes the item no longer a child of another item.

Inputs: itemId (required).

search_barcodeA

Search for product information using a barcode (EAN/UPC). Returns product details from barcode lookup services.

Inputs: barcode (required).

search_itemsC

Search for items using a query string. Searches across item names, descriptions, and other fields.

Inputs: query (required), page, pageSize.

set_item_parentA

Set or change the parent item for an item. This creates a parent-child relationship where the item becomes a child of another item (e.g., putting an item inside a box).

Inputs: itemId (required), parentId (required).

update_itemB

Update an existing inventory item

Inputs: id (required), name, description, locationId, +9 more.

update_labelB

Update an existing label's name, description, or color.

Inputs: id (required), name, description, color.

update_locationB

Update an existing location's name, description, or parent.

Inputs: id (required), name, description, parentId.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 21 tools

    Disambiguation5/5

    Each tool targets a distinct operation or resource. There is no overlap between item, label, location, or barcode operations. Even similar tools like get_item and search_items serve different lookups (exact ID vs query).

    Naming Consistency4/5

    Most tools follow verb_noun pattern (list_items, create_item, update_item). Exceptions include add_item_field (add vs create) and remove_item_parent (remove vs delete). 'get_locations_tree' uses plural 'locations', and 'search_barcode' differs from 'search_items'. Overall consistent but with minor deviations.

    Tool Count5/5

    21 tools is well-scoped for a home inventory management server. Each tool serves a clear purpose without excess, covering items, locations, labels, attachments, fields, and barcode search.

    Completeness5/5

    The tool set provides full CRUD for items, locations, and labels, plus attachments, custom fields, parent relationships, tree hierarchy, item links, and barcode search. No obvious missing functionality for typical home inventory tasks.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for managing Homebox inventory via AI assistants, enabling item management, location organization, and label categorization.
      5
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables AI assistants to query and explore Homebox home inventory data in real-time, with tools for searching items, listing locations and labels, and retrieving item details.
      9
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with a Homebox inventory system to search, create, update, and manage items, locations, and labels.
      ISC
    • A
      license
      A
      quality
      F
      maintenance
      Enables AI assistants to manage 3D printing inventory, filament spools, printers, projects, and print trackers through a self-hosted Print Vault instance.
      40
      AGPL 3.0