homebox-mcp

homebox-mcp

一个基于 Homebox REST API 的 MCP 服务，让 Claude 这样的 MCP 客户端能用自然语言管理你的家庭库存："我的冲击起子在哪里？"、"B-3 收纳箱里有什么？"、"今年有哪些保修到期？"、*"添加这把电钻——这是收据照片和型号。" *它可以回答问题、登记物品（创建物品、附加说明书或收据、添加标签并归档）、管理附件，还能为收纳箱和货架打印二维码标签——无需手写 curl。

快速开始

你需要一个正在运行的 Homebox 实例（0.26+，参见要求），以及从 Homebox 网页界面的 Profile → API Keys 获取的 API 密钥。

Claude Code

claude mcp add homebox --scope user \
  -e HOMEBOX_URL=https://homebox.example.com \
  -e HOMEBOX_TOKEN=hb_xxxxxxxxxxxxxxxxxxxxxxxx \
  -- uvx homebox-mcp
claude mcp get homebox      # should show: Status ✔ Connected

--scope user 可让它在任何项目中使用。uvx 会在临时环境中获取并运行已发布的软件包，无需预先安装任何内容。

Claude Desktop / 通用 MCP 客户端

将以下内容添加到客户端的 MCP 配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "homebox": {
      "command": "uvx",
      "args": ["homebox-mcp"],
      "env": {
        "HOMEBOX_URL": "https://homebox.example.com",
        "HOMEBOX_TOKEN": "hb_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

从克隆仓库运行（无 PyPI）

该模块包含 PEP 723 内联依赖，因此也可以通过 uv run --script 独立运行——首次运行时，uv 会将 mcp、httpx、pillow 和 pillow-heif 解析并安装到临时 venv 中。无需使用环境变量，只需将凭据放入模块旁边的 .env 文件：

git clone https://github.com/dgahagan/homebox-mcp
cd homebox-mcp
cp .env.example .env        # .env is gitignored
chmod 600 .env
# edit .env: HOMEBOX_URL + HOMEBOX_TOKEN

然后注册模块的绝对路径（也可以指向 server.py，这是为旧注册方式保留的兼容垫片）：

claude mcp add homebox --scope user -- \
  uv run --script /path/to/homebox-mcp/homebox_mcp.py

服务会从环境变量读取配置，若未设置，则回退到同级 .env 文件（相对于脚本解析，因此使用绝对路径调用时仍能找到该文件）。凭据不会进入 MCP 配置，而是留在被 git 忽略的 .env 文件中。

要求

• Homebox 0.26 或更高版本——使用目前仍在积极维护的 sysadminsmedia 分支，网址为 homebox.software。此服务使用 0.26 中引入的统一 entities API。较旧的实例使用不同的 API（/items、/locations、/labels），首次调用工具时会明确报错，而不是出现难以理解的故障。
• API 密钥——在 Homebox 的 Profile → API Keys 中获取（令牌以 hb_ 开头）。
• uv，或自行安装 homebox-mcp 的任意 Python ≥ 3.11 环境。
• MCP SDK 2.x（mcp>=2,<3），会自动安装。uvx/pipx 会构建隔离环境，因此无需额外操作。如果你要安装到已将 mcp<2 固定为依赖的环境中，请继续使用 homebox-mcp==1.0.1。

配置

所有配置均通过环境变量设置（克隆仓库工作流也可使用同级 .env 文件）：

变量	必填	用途
HOMEBOX_URL	是	Homebox 实例的基础 URL（末尾不要加斜杠）。
HOMEBOX_TOKEN	是	Homebox API 密钥（hb_…）。
HOMEBOX_ALIAS_FIELD	否	指定一个自定义字段，将其用作稳定的物品标识符——可按此字段解析物品、在摘要中显示该字段，并将其作为 field_index 的默认值。未设置时，只能按 assetId/name 解析。参见约定。
HOMEBOX_LABEL_DIR	否	generate_label / qrcode 的输出保存位置。默认值：当前工作目录。

工具

约 39 个工具。读取操作接受模糊标识符（assetId、别名字段、精确名称，然后是第一个关键词匹配项）。写入工具要求使用精确标识符（assetId、别名字段或精确名称）——拼写错误或匹配结果有歧义时会被拒绝，而不会修改错误的条目。assetId 必须采用完整的 000-012 格式：单独的 12 会按名称或别名匹配，绝不会被视为 asset 000-012。位置通过名称或以 / 分隔的路径引用（例如 Garage/Shelf 1），以区分同名位置。

读取 / 问答

工具	用途
search_items(query?, tags?, limit=20)	按关键词和/或标签名称搜索条目（两者同时提供时取交集）；每条结果包含 assetId、位置和别名字段。
get_item(identifier)	获取单个条目的完整详情：位置路径、身份信息、购买信息、保修信息、自定义字段、标签、附件。
list_locations()	以缩进大纲形式列出完整的位置树。
location_contents(location, recursive=False)	列出某个位置中的直接条目和子位置名称；recursive=True 会遍历整个子树，并返回所有嵌套条目及其完整位置路径。
list_tags(detail=False)	列出所有标签名称；detail=True 返回完整对象（描述、颜色、图标、父标签）。
warranties_expiring(before?, after?, lifetime=False)	列出保修到期时间在 after…before 范围内的条目（after 默认为今天，不包括已过期条目）；lifetime=True 列出终身保修条目。

创建和入库

工具	用途
create_item(name, location?, quantity=1, manufacturer?, model?, serial?, purchase_price?, purchase_date?, purchase_from?, warranty_expires?, notes?, fields?, tags?)	一次调用即可创建条目并补充信息。fields 是按 JSON 值类型填写的字典（string→文本，number→数字 [转换为整数]，bool→布尔值）；tags 必须是已存在的标签。location 的解析方式与 move_item 相同：位置名称或路径，或容器条目（名称、路径或 assetId）。返回新条目的 assetId。
import_csv(csv_text)	在一个 multipart 请求中，从 Homebox CSV 批量创建条目和位置。HB.location 会自动创建路径层级；可识别 HB.name、HB.tags、HB.quantity、HB.serial_number、HB.model_number、HB.manufacturer、HB.notes、HB.purchase_*、HB.warranty_expires、HB.field.<name>。
create_location(name, parent?, description?)	创建位置（收纳箱／储物箱／架子），以便设置新的存放地点；description 也可用作内容清单。
barcode_lookup(code)	UPC/EAN → 名称／制造商／型号（可选，适用于盒装商品）。
duplicate_item(identifier, copy_attachments=False, copy_custom_fields=True, copy_maintenance=False, prefix="Copy of ")	复制条目（“我又买了一个”）。复制的自定义字段会原样包含别名字段——之后请为副本设置独立的值。

编辑

所有写入工具都会按精确标识符解析，并保留你未修改的所有内容（完整正文 PUT 会将项目的其余内容一并传回——参见 注意事项）。

工具	用途
set_item(identifier, new_name?, description?, notes?, quantity?, purchase_price?, purchase_date?, purchase_from?, insured?, archived?, fields?)	通用物品编辑器：重命名、编辑备注、数量、购买信息、投保／归档标记和自定义字段。仅编辑数量时使用部分 PATCH。
move_item(identifier, location)	将物品移至某个位置或另一个物品中（例如将镜头放入 Camera Bag）。目标可以是位置名称或路径，与之前相同；只有在找不到匹配的位置时，才会按精确名称或路径（例如 Office/Camera Bag）查找目标物品，也可以提供该物品的 assetId。如果名称匹配到多个结果，则会拒绝操作；如果要移动的对象是位置，也会拒绝操作——请改用 set_location（部分 PATCH——其他内容不会改变）。
set_warranty(identifier, expires?, lifetime?, details?)	设置保修截止日期、终身保修标记和条款摘要。
set_identity(identifier, manufacturer?, model_number?, serial_number?)	设置制造商／型号／序列号（例如，铭牌照片显示这些信息后）。
set_fields(identifier, fields)	创建或覆盖自定义字段（更新或插入；类型由 JSON 值类型决定）。
set_tags(identifier, tags, mode="add")	添加／移除／替换物品上的标签；未知标签名称会自动创建（部分 PATCH）。
set_tag(name, new_name?, description?, color?, icon?, parent?, clear_parent=False)	编辑标签自身的元数据（重命名、颜色、图标、用于分组的父标签）——不会修改物品上的标签。若标签不存在则会创建。
set_location(location, new_name?, parent?, clear_parent?, description?, notes?, tags?, tags_mode?, entity_type?, asset_id?, fields?)	通用位置编辑器：重命名、移动（或使用 clear_parent 移至根级）、编辑标签、备注、实体类型、assetId 和自定义字段。
mark_sold(identifier, sold_price?, sold_to?, sold_date?, sold_notes?, clear=False)	记录出售情况（价格／买家／日期／备注），或设置 clear=True 取消出售记录；可配合 set_item(archived=True) 将物品退役。

维护日志

工具	用途
log_maintenance(identifier, name, description?, completed_date?, scheduled_date?, cost?)	添加一条记录——“今天给割草机换了机油”（已完成）或“春天磨刀片”（已安排）。
list_maintenance(identifier?, status="both")	查看某件物品的记录，或查看整个库存中的记录（“有哪些维护事项到期了？”）；status = 已安排／已完成／两者皆有。
set_maintenance(entry_id, ...)	编辑记录——例如，设置 completed_date，将已安排的事项标记为已完成。
delete_maintenance(entry_id, confirm)	删除一条记录（confirm = 该记录的确切名称）。

报告

工具	用途
inventory_stats(by="totals", start?, end?)	查看总计（数量、总价值、保修数量）、按位置或标签统计的价值，或随时间变化的购买价格——快速回答“我的库存值多少钱？”
export_csv(save_to?)	将整个库存导出为 Homebox CSV（与 import_csv 配套；可快速备份）。
list_custom_fields(field?)	查看正在使用的自定义字段架构：所有字段名称，或某个字段的每个不同取值。

附件

工具	用途
attach_document(identifier, source, title, doc_type="manual", primary=False)	将文件（本地 路径或 http(s) URL）附加到物品，或在找不到物品时按名称附加到位置。doc_type 示例：manual/receipt/warranty/photo；primary=True 会将照片设为实体的主图（例如位置的“此处即目的地”导航照片）。
list_attachments(identifier)	列出物品或位置的附件 及其 ID（其他附件工具所需的标识符）。
get_attachment(identifier, attachment_id, save_to)	将一个附件下载到本地路径，以便读取其内容（例如手册）。
rename_attachment(identifier, attachment_id, title?, doc_type?, primary?)	更新附件的标题、类型或主图标记。

上传时会自动将 HEIC/HEIF（iPhone 照片）转换为 JPEG，确保 Homebox 始终存储可在浏览器中显示的图像；同时会清理标题中的 /（Homebox 会将标题视为路径，否则会截断标题）。

删除（需确认）

每次删除都必须将 confirm 设置为目标的确切名称，并带有 MCP destructiveHint 注解，因此客户端会在执行前提示确认。

工具	用途
delete_item(identifier, confirm)	永久删除物品及其附件。无法撤销。
delete_location(location, confirm, confirm_nonempty=False)	删除位置。非空位置将被拒绝删除，除非 confirm_nonempty=True：子位置会级联删除；物品会移至顶层成为孤立物品（不会被删除）。
delete_tag(name, confirm)	删除标签本身（从所有带该标签的物品中移除；物品仍会保留）。
delete_attachment(identifier, attachment_id, confirm)	删除一个附件（confirm = 其确切标题）。

标签与收尾

工具	用途
generate_label(identifier, kind="location", out_dir?)	保存可打印的 location、item 或 asset 标签 PNG（二维码 + 易读名称）。保存到 $HOMEBOX_LABEL_DIR（否则保存到 CWD）。
qrcode(data, out_dir?)	将任意数据保存为原始二维码 JPEG（为收纳箱生成二维码时优先使用 generate_label，它会添加名称）。
finalize_photos()	批量附加照片后完成收尾：设置缺失的主图，然后生成缺失的缩略图。
field_index(field_name?)	自定义字段上的 {field_value: assetId} 索引（默认 $HOMEBOX_ALIAS_FIELD）——批量导入前用于一次性 去重，因为 q 不会索引自定义字段。

工作原理（以及 Homebox 0.26 的注意事项）

此服务的价值不仅在于它提供的功能，也在于它规避了哪些问题。以下是针对 0.26 实体 API，总结出的实战经验：

• 物品和位置统一为“实体”（/v1/entities）；位置是 isLocation=true 的实体类型实体。新建物品时，如果没有 entityTypeId，系统会按需分配默认的 Item 类型。
• GET /entities 只返回非位置实体。 位置的子级不会出现在 /entities 结果中，即使提供了 parentIds 也一样；子位置需从实体树（/entities/tree）获取。location_contents 会合并这两个来源，delete_location 的非空检查会同时统计物品和子位置。
• 删除非空位置会级联删除子位置，但会使物品成为孤立项。 强制删除位置（confirm_nonempty=True）时，其子位置会一并删除，但其中的物品会保留，并移至顶层。如果不想让物品失去归属，请先将其移出。
• 列表／搜索响应是轻量摘要——不包含 fields，且 assetId 为空。服务器会先获取完整详情（GET /entities/{id}），再返回 assetId／别名，因此 search_items／get_item 的结果准确。
• q 不会索引自定义字段。 通过别名字段值查找时，会回退到扫描（每个物品获取一次详情）。通过 assetId（经由 /v1/assets/{id}）或名称查找成本更低——如果有 assetId（例如 create_item 返回的值），优先使用它。
• PUT 会清除未提供的字段，包括 assetId。每个写入工具都会基于最新 GET 的结果重建完整请求体（_preserve_item_body），并只覆盖目标键。create_item 会在数据补全后分配资产 ID，以确保其保留。
• 附件标题会按 / 分段取名。 Homebox 会将标题视为类似路径的内容，因此 "front 3/4 view" 会被静默保存为 "4 view"。服务器会将附件标题中的 / 清理为 -。
• 数字自定义字段采用整数类型。 浮点型 numberValue（例如 MCP SDK 根据 float 类型的参数生成的 17000.0）会导致 API 返回 500 "Unknown Error"。服务器会将数字值强制转换为 int；请传入整数。
• 自定义字段值按类型区分（textValue／numberValue／booleanValue）。服务器会根据字段声明的类型重建字段——如果一律强制转换为 textValue（早期的一个 bug），任何 PUT 都会静默清除数值／布尔字段。
• 分页。 超过一页（200 条）的实体列表会被静默截断；服务器会持续分页，直到达到报告的 total，确保大型库存中的搜索、去重和保修检查结果准确。

约定（可选）

Homebox 内置的 assetId 是稳定的数字标识，但不适合凭记忆输入。如果你需要一个有意义且稳定的人类可读标识符，以便将物品与收据、电子表格或其他系统交叉引用，可以添加一个自定义字段（例如 item_id），用于存储类似 makita-xdt131 的简短标识，并将 HOMEBOX_ALIAS_FIELD 指向该字段。这样：

• 每个读取和写入工具都能通过该标识查找物品；
• search_items／get_item 摘要会显示该标识；并且
• field_index() 默认使用该字段，在批量导入前只需一次调用即可获得去重映射。

这完全是可选的——不设置 HOMEBOX_ALIAS_FIELD 时，物品只能通过 assetId 或名称查找。字段名称没有任何特殊要求；任意一个自定义字段都可以。

配套脚本

仓库中附带两个独立的辅助脚本（不是 MCP 工具）：

• annotate_location_photos.py 可将一张货架组的全景照片转换为每个货架一张带框和标签的图片（--rows N），并可通过 --upload 将每张图片直接上传到对应的 Homebox 位置。参见其 --help。
• heic2jpg.py 可将 HEIC/HEIF（iPhone 照片）转换为 JPEG，供临时使用（./heic2jpg.py FILE...）。请注意，附件工具已会在上传时自动转换 HEIC，因此只有在上传前需要将 HEIC 帧传入视觉步骤时才需要用到此脚本。

两者都依赖 pillow-heif，它捆绑了 libheif，无需安装系统软件包。

安全

• API 密钥处理。 在克隆工作流中，密钥保存在 .env 中，该文件已被 git 忽略，权限应设为 600（chmod 600 .env）。切勿提交该文件。在 uvx 工作流中，密钥通过 MCP 客户端的配置传入——也应将该文件视为机密。
• 密钥轮换。 轮换 Homebox 的 HBOX_AUTH_API_KEY_PEPPER 会使所有已签发的密钥失效——请生成新密钥并更新配置。
• 删除操作需确认。 四个删除工具都要求 confirm 与目标的确切名称相同，并带有 MCP destructiveHint 注解，因此行为良好的客户端会在执行任何破坏性调用前提示确认。
• 对任何远程 Homebox 实例都应使用 HTTPS——每次请求都会在 Authorization 标头中发送 API 密钥。

开发

git clone https://github.com/dgahagan/homebox-mcp
cd homebox-mcp

# Run the test suite (httpx mocked with respx — no live instance needed)
uv run --with pytest --with respx --with . pytest

# Lint
uv run --with ruff ruff check .

该服务是一个单模块（homebox_mcp.py），包含 PEP 723 内联依赖项。有关设置和 PR 要求，请参见 CONTRIBUTING.md；有关发布说明，请参见 CHANGELOG.md。

许可证

MIT © Dan Gahagan