HomeBoxMCP

Habla con tu inventario del hogar. HomeBoxMCP es un servidor MCP pequeño y sin estado que acerca tu inventario de Homebox a cualquier cliente MCP: Claude, o cualquier otra herramienta que hable el protocolo. Pregunta dónde está el taladro, registra una nueva compra con su recibo adjunto o reorganiza un armario entero, en lenguaje natural.

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

Dieciséis herramientas, un solo archivo, cero dependencias en tiempo de ejecución: solo Node 22 y node:http. Colócalo detrás de Docker y olvídate de él.

Por qué este

• Lectura y escritura. Que no te engañe el homebox-mcp de solo lectura de terceros. Este crea, actualiza, mueve, elimina y adjunta archivos.

• Creado para Homebox v0.26.x. Apunta a la API entity, donde los artículos y las ubicaciones se unifican como «entities» y las etiquetas pasa a llamarse «tags».

• HTTP con streaming sin estado. Sin almacén de sesiones, sin base de datos, sin sidecar. Reinícialo cuando quieras.

• Falla con claridad, no de forma rara. --doctor valida tu conexión con Homebox antes de que el servidor acepte cualquier petición, y las subidas demasiado grandes se rechazan mostrando el tamaño real en lugar de un 422 opaco.

Related MCP server: AllOurThings MCP Server

Inicio rápido

Descarga la imagen publicada:

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

O compila desde el código fuente:

docker build -t homeboxmcp:latest .

Apunta tu cliente MCP a http://your-host:3334/mcp; esa ruta es obligatoria. Un POST a cualquier otra devuelve un 404 que indica el endpoint correcto. Comprueba que el servidor está vivo con curl http://your-host:3334/healthz, que informa de la versión y del número de herramientas.

¿Prefieres comprobar primero la configuración? --doctor verifica que la URL de Homebox es alcanzable y que las credenciales funcionan de verdad. Si no, termina con un código de salida distinto de cero e indica el motivo.

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

Unraid

Una plantilla de Unraid se encuentra en unraid/homeboxmcp.xml. Añádela en Docker → Add Container → Template usando la URL directa, o una vez esté disponible, desde Community Apps. Configura las rutas de configuración y de la bandeja de entrada para que apunten a recursos compartidos que tú controlas, y asigna un token de autenticación de MCP si el contenedor va a ser accesible fuera de tu LAN.

Configuración

Escribe /config/config.json:

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

O prescinde por completo del archivo y usa HOMEBOX_URL con HOMEBOX_API_KEY; o HOMEBOX_URL con correo y contraseña, si prefieres que HomeBoxMCP se autentique por su cuenta.

Si expones HomeBoxMCP más allá de tu propia máquina, define MCP_AUTH_TOKEN. Los clientes pueden enviarlo como Authorization: Bearer <token>, X-MCP-Token o X-Homebox-MCP-Token.

Las herramientas

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

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

Adjuntos — list_inbox, upload_attachment, delete_attachment, link_external_attachment

Adjuntos, ¿y por qué existe una bandeja de entrada?

Las llamadas a las herramientas de MCP transportan JSON, no datos binarios. Incrustar un recibo de 10 MB como base64 costaría unos 13 MB del contexto del modelo para mover un solo archivo. Así que los archivos llegan a HomeBoxMCP mediante un montaje de bandeja de entrada de solo lectura: coloca el archivo en la bandeja y luego adjúntalo por su nombre.

Las rutas se interpretan dentro de la bandeja de entrada y se rechazan si intentan escapar de ella; tanto ../../etc/passwd como las rutas absolutas no pasar. Los tipos de adjuntos válidos son attachment, photo, manual, warranty, receipt y thumbnail.

Origen

Este repositorio existe porque HomeBoxMCP (entonces llamado homebox-shim en aquel momento) se descubrió en ejecución sin código fuente en disco, y la única copia de index.mjs vivía dentro de una imagen Docker en ejecución, sin un Dockerfile en ningún lugar. Se recuperó con docker cp Homebox-Shim:/app/index.mjs y se reconstruyó el Dockerfile desde la propia configuración de la imagen. Ahora este repositorio es la fuente de verdad. Reconstruye desde aquí, no desde la imagen.

Consulta docs/SUPPORTABILITY.md para ver el documento que motivó la recuperación.

Licencia

MIT — ver LICENSE.