Homebox MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Homebox MCP Server list all items in the Living Room location"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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
Option 1: Install from npm (Recommended)
The easiest way to get started is to install the package directly from npm:
npm install -g homebox-mcpNote: 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.shWindows:
update.batOr manually:
npm update -g homebox-mcpOption 2: Install from Source
Clone this repository:
git clone https://github.com/danielrosehill/Homebox-MCP-1125.git
cd Homebox-MCP-1125Install dependencies:
npm installBuild the server:
npm run buildConfiguration
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 tofalseto use WAN for APILAN_LINKS- (Optional) Use LAN for display links (default:false). Set totrueto 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 keyHOMEBOX_PASSWORD- Your Homebox password - only needed if not using API key
Note: If both
HOMEBOX_API_KEYand 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 performanceSet
USE_LAN_API=falseto 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=trueto 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
Open LM Studio
Go to Settings → MCP Servers
Add a new server with the following configuration:
Name: Homebox
Command:
npx(orhomebox-mcpif globally installed)Args:
homebox-mcp(if using npx; leave empty if using global install)Environment Variables:
HOMEBOX_LOCAL_URL:http://10.0.0.4:7745HOMEBOX_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_USERNAMEandHOMEBOX_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-c952c1deafc5Searching
"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 filteringget_item- Get detailed information about a specific itemget_item_link- Get direct link to an item by asset ID, name, or description (recommended for getting links!)create_item- Create a new inventory itemupdate_item- Update an existing itemdelete_item- Delete an itemsearch_items- Search for items using a query stringset_item_parent- Set or change the parent item for an item (creates parent-child relationship)remove_item_parent- Remove the parent relationship from an itemadd_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 locationscreate_location- Create a new location
Labels
list_labels- List all labels/tagscreate_label- Create a new label
Development
Running in Development Mode
npm run devBuilding
npm run buildRunning the Built Version
npm startExample:
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-c952c1deafc5Database 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 toolsadd_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_item_linkA
Get the direct link to an item by searching for it using asset ID, name, or description. This is the preferred tool when users ask for links to specific items. Returns the direct clickable URL.
Inputs: query (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
Scored across 21 tools
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).
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.
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.
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
Related MCP Connectors
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
AI assistant integration for Leaf — track books, log reading sessions, and manage your library.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Connect an AI assistant to a Capacities space (objects, daily notes, search).
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for managing Homebox inventory via AI assistants, enabling item management, location organization, and label categorization.5MIT
- AlicenseNot gradedqualityFmaintenanceEnables 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.9MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with a Homebox inventory system to search, create, update, and manage items, locations, and labels.ISC
- AlicenseAqualityFmaintenanceEnables AI assistants to manage 3D printing inventory, filament spools, printers, projects, and print trackers through a self-hosted Print Vault instance.40AGPL 3.0