HomeBoxMCP

与你的家庭库存对话。 HomeBoxMCP 是一个小巧、无状态的 MCP 服务器，可让你的任何 MCP 客户端——Claude，或任何支持这种协议的其他客户端——触达 Homebox 库存。用日常语言问电钻在哪里，记录一笔附带收据的新购买，或重新整理整个储物柜。

"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 后面，就不用再管它。

为什么选择这个

• 可读 和 可写。 不要与第三方只读的 homebox-mcp 混淆。这个可以创建、更新、移动、删除和附加文件。

• 为 Homebox v0.26.x 构建。 目标使用 entity API，其中物品和位置统一为 “entities”，标签也更名为 “tags”。

• 无状态、可流式 HTTP。 没有会话存储，没有数据库，没有边车进程。随时重启都可以。

• 失败时大声报错，而不是莫名其妙。 --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——该路径是强制的，其他任何位置的访问路径都会返回 404 并指明正确的端点。使用 curl http://your-host:3334/healthz 检查服务器是否存活，它会返回版本号和工具数量。

更想先检查一下配置？--doctor 会验证 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 下通过“原始 URL”添加它，或者在列出后从 Community Apps 安装。将配置和收件箱路径设置为你控制的共享目录；如果容器在局域网之外也可达，请设置一个 MCP 认证令牌。

配置

在 /config/config.json 中写入：

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

或者完全跳过该文件，改用 HOMEBOX_URL 加 HOMEBOX_API_KEY；如果你更希望 HomeBoxMCP 自行登录，也可以用 HOMEBOX_URL 加电子邮件和密码。

如果你将 HomeBoxMCP 暴露到自己的机器之外，请设置 MCP_AUTH_TOKEN。客户端可以将其作为 Authorization: Bearer <token>、X-MMM-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

附件，以及为什么需要一个收件箱

MCP 工具调用传输的是 JSON，而不是二进制。把一个 10 MB 的收据以内嵌 base64 的形式发送，会为了移动一个文件而消耗模型约 13 MB 的上下文。因此，文件改为通过只读的收件箱挂载到达 HomeBoxMCP：把文件放进收件箱，然后按文件名进行附加。

路径会相对于收件箱解析，并会在尝试逃逸时被拒绝——../../etc/passwd 和绝对路径都以失败关闭（fail closed）的方式被拒绝。可用的附件类型有 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。