HomeBoxMCP

Talk to your home inventory. HomeBoxMCP — это небольшой MCP-сервер без сохранения состояния, который открывает ваш инвентарь Homebox для любого MCP-клиента — Claude или любого другого, кто работает с этим протоколом. Спросите, где дрель, добавьте новую покупку с прикреплённым чеком или переструктурируйте целый шкаф — простыми словами.

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

Шестнадцать инструментов, один файл, ноль зависимостей времени выполнения — нужны только Node 22 и node:http. Поставьте его за Docker и забудьте.

Почему именно этот

• Чтение и запись. Не путать со сторонним read-only homebox-mcp. Этот сервер создаёт, обновляет, перемещает, удаляет и прикрепляет файлы.

• Создан для Homebox v0.26.x. Нацелен на API entity, где предметы и местоположения объединены как «entities», а метки переименованы в «tags».

• Потоковый HTTP без состояния. Никаких хранилищ сессий, баз данных и sidecar-контейнеров. Перезапускайте его, когда захочется.

• Падает громко, а не странно. --doctor проверяет подключение к Homebox до того, как сервер примет хотя бы один запрос, а слишком большие загрузки отклоняются с указанием фактического размера вместо непонятного 422.

Related MCP server: Homebox MCP Server

Быстрый старт

Скачайте опубликованный образ:

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

Или соберите из исходников:

docker build -t homeboxmcp:latest .

Направьте ваш MCP-клиент на http://your-host:3334/mcp — этот путь обязателен; POST по любому другому адресу вернёт 404 с именем правильной конечной точки. Проверьте, что сервер жив, командой curl http://your-host:3334/healthz, которая выводит версию и количество инструментов.

Хотите сперва проверить конфигурацию? --doctor проверяет, что URL Homebox доступен и что учётные данные действительно рабочие, а затем завершается с ненулевым кодом и однострочной причиной, если это не так:

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

Unraid

Шаблон Unraid находится в unraid/homeboxmcp.xml. Добавьте его в разделе Docker → Add Container → Template с помощью raw-ссылки, либо установите из Community Apps, когда он появится в списке. Укажите пути к конфигурации и inbox в сетевых папках, которыми вы управляете, и задайте MCP-auth токен, если контейнер доступен извне вашей локальной сети.

Конфигурация

Создайте /config/config.json:

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

Либо вообще откажитесь от файла и используйте HOMEBOX_URL вместе с HOMEBOX_API_KEY — или HOMEBOX_URL с email и паролем, если вы предпочитаете, чтобы HomeBoxMCP авторизовался сам.

Если вы открываете доступ к HomeBoxMCP за пределами своей машины, установите MCP_AUTH_TOKEN. Клиенты могут передавать его как Authorization: Bearer <token>, X-MCP-Token или X-Homebox-MCP-Token.

16 инструментов

Чтение — search_entities, entity_tree, get_entity, list_tags, list_entity_types, get_stats

Запись — create_location, create_item, update_entity, move_entity, delete_entity, create_tag

Вложения — list_inbox, upload_attachment, delete_attachment, link_external_attachment

Вложения и для чего нужен inbox

Вызовы инструментов MCP передают JSON, а не бинарные данные. Встраивание чека на 10 МБ в base64 сожжёт ~13 МБ контекста модели ради одного файла. Поэтому файлы попадают в HomeBoxMCP через read-only inbox mount: положите файл в inbox и прикрепите его по имени.

Пути разрешаются относительно inbox и отклоняются, если пытаются выйти за его пределы — ../../etc/passwd и абсолютные пути в обоих случаях безопасно отклоняются. Допустимые типы вложений: attachment, photo, manual, warranty, receipt и thumbnail.

История появления

Этот репозиторий появился потому, что HomeBoxMCP (тогда ещё homebox-shim) был обнаружен работающим без исходников на диске — единственная копия index.mjs жила внутри запущенного Docker-образа, и Dockerfile нигде не было. Файл был извлечён через docker cp Homebox-Shim:/app/index.mjs, а Dockerfile восстановлен из конфигурации самого образа. Теперь этот репозиторий — единственный источник истины. Собираем отсюда, а не из образа.

См. docs/SUPPORTABILITY.md — обзор, который привёл к восстановлению.

Лицензия

MIT — см. LICENSE.