Homebox

MCP for Homebox with support for LAN and WAN URLs

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio supermaxman-homebox-mcp-server npx homebox-mcp \
  --env LAN_LINKS="false" \
  --env USE_LAN_API="true" \
  --env HOMEBOX_API_KEY="your_api_key_here" \
  --env HOMEBOX_WAN_URL="" \
  --env HOMEBOX_PASSWORD="your_password" \
  --env HOMEBOX_USERNAME="your_email@example.com" \
  --env HOMEBOX_LOCAL_URL="http://10.0.0.4:7745"

How to use

Homebox MCP Server exposes a bridge between your Homebox instance and AI assistants or local LLM tooling. It lets you manage inventory items, locations, and labels using natural language or function-calling-enabled prompts. You can list, create, update, and delete items; manage hierarchical locations; and view item/web links that adapt to your LAN/WAN context. The server supports flexible URL configuration so that API calls can use LAN for speed while web links can point to WAN when available, or vice versa depending on your environment. Typical workflows include asking the assistant to locate items, move inventory between locations, or generate shareable links for assets.

How to install

Prerequisites:

Node.js 18+ (or a runtime that supports the MCP server as described)
Access to a running Homebox instance
Optional: Homebox API key (recommended) or username/password

Option A: Install from npm (recommended)

Install globally from npm:

npm install -g homebox-mcp

Run or configure via MCP framework (see mcp.json examples below)

Option B: Install from Source

Clone the repository:

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

Install dependencies:

npm install

Build the server (if required):

npm run build

Start the server using your preferred method (e.g., node dist/index.js or via your MCP manager).

Configuration notes:

Use the provided mcp.json/mcpServers fragment and customize environment variables to point to your Homebox instance.
Ensure HOMEBOX_LOCAL_URL is set to your LAN API endpoint (e.g., http://10.0.0.4:7745).
Provide either HOMEBOX_API_KEY or HOMEBOX_USERNAME/HOMEBOX_PASSWORD for authentication. If both API key and credentials are present, the API key takes precedence.

Additional notes

Tips and common issues:

If you see authentication errors, verify that either HOMEBOX_API_KEY is valid or that the username/password pair works, and that the Homebox instance is reachable from the MCP server host.
For best performance, prefer LAN API calls by setting USE_LAN_API to true; set LAN_LINKS to true to force LAN links for asset presentation.
When WAN URLs are provided, the MCP server can generate shareable links that remain accessible off-LAN. If WAN URL is not configured, the server will fall back to LAN.
If you upgrade Homebox or the MCP server, re-check environment variable names and API endpoints as the API surface can change.
If you run into port or network restrictions, ensure the hosting environment allows outbound API connections to your Homebox instance.

Related MCP Servers

zen

1.1k

Selfhosted notes app. Single golang binary, notes stored as markdown within SQLite, full-text search, very low resource usage

MCP -Deepseek_R1

A Model Context Protocol (MCP) server implementation connecting Claude Desktop with DeepSeek's language models (R1/V3)

mcp-fhir

A Model Context Protocol implementation for FHIR

mcp

Inkdrop Model Context Protocol Server

mcp-appium-gestures

This is a Model Context Protocol (MCP) server providing resources and tools for Appium mobile gestures using Actions API..

dubco -npm

The (Unofficial) dubco-mcp-server enables AI assistants to manage Dub.co short links via the Model Context Protocol. It provides three MCP tools: create_link for generating new short URLs, update_link for modifying existing links, and delete_link for removing short links.