HomeBoxMCP

Sprich mit deinem Haushaltsinventar. HomeBoxMCP ist ein kleiner, zustandsloser MCP-Server, der dein Homebox-Inventar in die Reichweite jedes MCP-Clients bringt — Claude oder alles andere, was das Protokoll spricht. Frag, wo die ist, lege einen neuen Kauf mit dem beigefügten Beleg an oder räume einen ganzen Schrank neu ein, in einfacher Sprache.

"Where did I put the spare HDMI cables?"
"Add the new espresso machine to the kitchen — warranty expires 2028-04-01."
"Move everything on Shelf B to the garage overflow bin."

Sechzehn Tools, eine Datei, keine Laufzeitabhängigkeiten — nur Node 22 und node:http. Stell es hinter Docker und vergiss es.

Warum dieses

• Lesen und Schreiben. Nicht zu verwechseln mit dem Drittanbieter-homebox-mcp, das nur lesen kann. Dieses hier legt an, aktualisiert, verschiebt, löscht und hängt Dateien an.

• Gebaut für Homebox v0.26.x. Ziel ist die Entity-API, in der Gegenstände und Standorte zu „Entitäten“ zusammengeführt und Etiketten in „Tags“ umbenannt werden.

• Zustandsloses Streamable-HTTP. Kein Sitzungsspeicher, keine Datenbank, kein Sidecar. Starte es neu, wann immer du willst.

• Scheitert laut, nicht rätselhaft. --doctor prüft deine Homebox-Verbindung, bevor der Server überhaupt eine Anfrage annimmt, und zu große Uploads werden mit der tatsächlichen Größe abgewiesen, statt mit einer aussagelosen 422.

Related MCP server: AllOurThings MCP Server

Schnellstart

Lade das veröffentlichte Image herunter:

docker run -d --name HomeBoxMCP -p 3334:3334 \
  -v /path/to/config:/config:rw \
  -v /path/to/inbox:/inbox:ro \
  ghcr.io/businessnone/homeboxmcp:latest

Oder baue aus dem Quellcode:

docker build -t homeboxmcp:latest .

Richte deinen MCP-Client auf http://your-host:3334/mcp aus — dieser Pfad ist erzwungen: Ein POST woandershin liefert 404 und nennt den richtigen Endpunkt. Prüfe mit curl http://your-host:3334/healthz, ob der Server lebt; das meldet Version und Tool-Anzahl.

Ziehst du es vor, die Konfiguration zuerst zu prüfen? --doctor verifiziert, dass die Homebox-URL erreichbar ist und dass die Anmeldedaten tatsächlich funktionieren, und endet dann mit einem Nicht-Null-Exitcode und einer einzeiligen Begründung:

docker run --rm -v /path/to/config:/config:ro \
  ghcr.io/businessnone/homeboxmcp:latest node /app/index.mjs --doctor

Wenn er server not, then not.

docker run --rm -v /path/to/config:/config:ro \
  ghcr.io/businessnone/homeboxmcp:latest node /app/index.mjs --doctor

Unraid

Eine Unraid-Vorlage liegt unter unraid/homeboxmcp.xml. Füge sie unter Docker → Add Container → Template über die raw-URL hinzu oder installiere sie aus Community Apps, sobald sie gelistet ist. Setze die Konfiguration- und Inbox-Pfade auf Freigaben, die du kontrollierst, und setze ein MCP-Auth-Token, wenn der Container außerhalb deines LANs erreichbar ist.

Konfiguration

Lege /config/config.json an:

{ "homeboxUrl": "http://homebox:7745", "apiKey": "..." }

Oder lass die Datei ganz weg und verwende HOMEBOX_URL plus HOMEBOX_API_KEY — oder HOMEBOX_URL mit E-Mail und Passwort, falls du möchtest, dass sich HomeBoxMCP selbst anmeldet.

Wenn du HomeBoxMCP über dein eigenes System hinaus erreichbar machst, setze MCP_AUTH_TOKEN. Clients können das Token als Authorization: Bearer <token>, X-MCP-Token oder X-Homebox-MCP-Token senden.

Die 16 Tools

Lesen — search_entities, entity_tree, get_entity, list_tags, list_entity_types, get_stats

Schreiben — create_location, create_item, update_entity, move_entity, delete_entity, create_tag

Anhänge — list_inbox, upload_attachment, delete_attachment, link_external_attachment

Anhänge und warum es eine Inbox gibt

MCP-Toolaufrufe transportieren JSON und keine Binärdaten. Eine 10-MB-Quittung als base64 einzubetten würde rund 13 MB Werkzeugspeicher verbrauchen – nur um eine Datei zu bewegen. Deshalb erreichen Dateien HomeBoxMCP stattdessen über einen schreibgeschützten Inbox-Mount: Leg die Datei in die Inbox und dann anhand des Dateinamens als Anhang hinzu.

Pfade werden relativ zur Inbox auflöst und abgelehnt, wenn sie sie zu verlassen versuchen — ../../etc/passwd und absolute Pfade scheitern stets. Gültige Anhangstypen sind attachment, photo, manual, warranty, receipt und thumbnail.

Entstehung

Dieses Repository existiert, weil HomeBoxMCP (damals homebox-shim genannt) ohne Quellcode auf der Platte laufend entdeckt wurde – die einzige Kopie von index.mjs befand sich in einem laufenden Docker-Image und nicht What. Daher nirgends eine Dockerfile. Sie wurde mit docker cp Homebox-Shim:/app/index.mjs geborgen und die Dockerfile aus der fehlenden Konfiguration des Images rekonstruiert. Dieses Repository ist nun die Quelle der Wahrheit.