homebox-mcp

homebox-mcp

Homebox REST API を利用するMCPサーバーです。Claude のような MCP クライアントが、自然な言葉で自宅の持ち物を扱えるようになります。「インパクトドライバーはどこ？」、「トート B-3 には何が入ってる？」、「今年期限が切れる保証はどれ？」、*「このドリルを追加して — レシートの写真と型番はこちらです」*といった質問に答えます。持ち物の登録（アイテムの作成、取扱説明書やレシートの添付、タグ付けと分類）、添付ファイルの管理、トートや棚に貼る QR ラベルの印刷も行えます。curl を手作業で組み立てる必要はありません。

クイックスタート

Homebox の実行中のインスタンス（0.26 以降。［要件］を参照）と、Homebox の Web UI の 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 以降 — homebox.software で提供されている、活発に保守されている sysadminsmedia fork。このサーバーは 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	いいえ	1 つのカスタムフィールドを、安定したアイテム識別子として扱う際の名前です。このフィールドでアイテムを検索でき、概要にも表示されます。また、field_index の既定値にもなります。未設定の場合は、assetId／名前のみで検索します。［規約］を参照してください。
HOMEBOX_LABEL_DIR	いいえ	generate_label／qrcode の出力先です。既定値は現在の作業ディレクトリです。

ツール

約39個のツールがあります。読み取りでは あいまい検索 に対応した識別子（assetId、alias フィールド、完全一致する名前、キーワードの最初の一致）を受け付けます。書き込みツールには 完全一致する 識別子（assetId、alias フィールド、または完全一致する名前）が必要です。誤字や曖昧な一致がある場合、誤ったアイテムを変更する代わりに拒否されます。assetId は完全な 000-012 形式で指定してください。単独の 12 は名前またはエイリアスとして照合され、asset 000-012 としては扱われません。場所は、重複する名前を区別できるよう、名前または / 区切りのパス（例：Garage/Shelf 1）で指定します。

読み取り／Q&A

ツール	用途
search_items(query?, tags?, limit=20)	キーワードやタグ名（両方指定した場合は AND 条件）でアイテムを検索します。assetId、場所、alias フィールドを含む各アイテムを返します。
get_item(identifier)	1つのアイテムの詳細情報を取得します。場所のパス、識別情報、購入情報、保証、カスタムフィールド、タグ、添付ファイルが含まれます。
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?)	1回の呼び出しでアイテムを作成し、詳細情報を追加します。fields は JSON 値の型に応じた dict です（string→text、number→number［整数に変換］、bool→boolean）。tags は既存のタグである必要があります。location は move_item と同様に、場所の名前またはパス、あるいはコンテナーアイテム（名前、パス、assetId）として解決されます。新しい assetId を返します。
import_csv(csv_text)	1回の 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 ")	アイテムを複製します（「同じものをもう1つ買いました」）。複製されるカスタムフィールドには alias フィールドもそのまま含まれます。複製したアイテムには別の値を設定してください。

編集

すべての書き込みツールは識別子を完全一致で解決し、変更していない内容はすべて保持します（項目の残りの部分をそのまま返す、本文全体の 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")	1つのアイテム、または在庫全体のエントリーを表示します（「期限が来ているメンテナンスは？」など）。status は scheduled／completed／both です。
set_maintenance(entry_id, ...)	エントリーを編集します。たとえば、completed_date を設定して予定済みのメンテナンスを完了済みにします。
delete_maintenance(entry_id, confirm)	1つのエントリーを削除します（confirm にはそのエントリーの名前を完全一致で指定します）。

レポート

ツール	目的
inventory_stats(by="totals", start?, end?)	合計（件数、総額、保証件数）、場所またはタグ別の価値、または購入価格の推移を表示します。「在庫の価値はいくら？」に手軽に答えられます。
export_csv(save_to?)	在庫全体を Homebox CSV としてエクスポートします（import_csv の補完機能で、手軽にバックアップできます）。
list_custom_fields(field?)	使用中のカスタムフィールドのスキーマを確認します。すべてのフィールド名、または1つのフィールドの値の一覧を取得できます。

添付ファイル

ツール	用途
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)	添付ファイルを1つローカルパスにダウンロードし、内容（マニュアルなど）を読み取れるようにします。
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)	添付ファイルを1つ削除します（confirmには正確なタイトルを指定します）。

ラベルと仕上げ

ツール	用途
generate_label(identifier, kind="location", out_dir?)	印刷可能なラベルPNG（QRコードと読み取り可能な名前）を、location、item、またはasset用に保存します。$HOMEBOX_LABEL_DIRに保存します（設定されていない場合はCWD）。
qrcode(data, out_dir?)	任意のデータを含むQRコードJPEGを保存します。トートには名前が追加されるgenerate_labelの使用を推奨します。
finalize_photos()	写真をまとめて添付した後、未設定のメイン画像を設定し、不足しているサムネイルを生成して仕上げます。
field_index(field_name?)	カスタムフィールド（デフォルトは$HOMEBOX_ALIAS_FIELD）を対象とした{field_value: assetId}インデックスです。qではカスタムフィールドをインデックス化できないため、一括インポート前に1回の処理で重複排除するために使用します。

仕組みと Homebox 0.26 の注意点

このサーバーの価値は、公開する機能だけでなく、その周辺の問題にどう対処するかにもあります。以下は、0.26 のエンティティ API で得られた重要な知見です。

• アイテムとロケーションは統合された「エンティティ」です（/v1/entities）。ロケーションは、エンティティタイプの isLocation=true が設定されたエンティティです。entityTypeId を指定せずに新しいアイテムを作成すると、デフォルトの Item タイプが遅延生成されます。
• GET /entities が返すのは、ロケーション以外のエンティティのみです。 ロケーションの子要素は、parentIds を指定しても /entities の結果には表示されません。サブロケーションはエンティティツリー（/entities/tree）から取得します。location_contents は両方の取得元を統合し、delete_location の空判定ではアイテムとサブロケーションの両方を数えます。
• 中身のあるロケーションを削除すると、サブロケーションは連鎖削除されますが、アイテムは孤立します。 ロケーションを強制削除（confirm_nonempty=True）すると、サブロケーションは一緒に削除されますが、ロケーション内のアイテムは残り、最上位に再配置されます。アイテムを未配置の状態にしたくない場合は、先に移動してください。
• 一覧／検索のレスポンスは簡易サマリーです。 fields は省略され、assetId は空です。サーバーは assetId／エイリアスを返す前に、完全な詳細（GET /entities/{id}）を取得するため、search_items／get_item の結果は正確です。
• q はカスタムフィールドをインデックスしません。 エイリアスフィールドの値で解決する場合は、スキャンによるフォールバックが使われます（アイテムごとに詳細を 1 回取得）。/v1/assets/{id} 経由での assetId または 名前 による解決の方が低コストです。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 は 「Unknown Error」500 を返します。サーバーは数値を int に変換するため、整数を渡してください。
• カスタムフィールドの値は型ごとにキーが異なります（textValue／numberValue／booleanValue）。サーバーは宣言された型に応じて各フィールドを再構築します。以前の不具合では、すべてを textValue に変換していたため、PUT のたびに数値／ブール値フィールドが気付かないうちに消去されていました。
• ページネーション。 1 ページ（200 件）を超えるエンティティ一覧は、以前は気付かないうちに途中で切り詰められていました。サーバーは報告された total 件数に達するまでページを取得するため、大規模なインベントリでも検索、重複排除、保証期間の一括確認が正しく行われます。

規約（任意）

Homebox に組み込まれた assetId は安定した数値の識別子ですが、記憶を頼りに入力できるものではありません。レシート、スプレッドシート、または別のシステムとアイテムを相互参照する際に便利な、人にとって分かりやすく安定した識別子が必要な場合は、item_id などのカスタムフィールドを追加し、makita-xdt131 のようなスラッグを設定して、HOMEBOX_ALIAS_FIELD にそのフィールドを指定してください。すると、次のようになります。

• すべての読み取り／書き込みツールで、そのスラッグを使ってアイテムを解決できます。
• search_items／get_item のサマリーにその値が表示されます。
• field_index() がその値をデフォルトで使用するため、一括インポートの前に 1 回の呼び出しで重複排除用のマップを取得できます。

これは完全に任意です。HOMEBOX_ALIAS_FIELD を未設定のままにすると、アイテムは assetId または名前のみで解決されます。フィールド名に特別な意味はありません。どの単一のカスタムフィールドでも使用できます。

補助スクリプト

リポジトリには、単体で使える補助スクリプトが2つ含まれています（MCP ツールではありません）。

• annotate_location_photos.py は、棚一列を撮影した横長の写真1枚から、棚ごとに枠とラベルを付けた画像を1枚ずつ作成します（--rows N）。また、--upload を指定すると、各画像を対応する Homebox のロケーションに直接アップロードできます。--help を参照してください。
• heic2jpg.py は、HEIC／HEIF（iPhone の写真）を JPEG に変換します（単発での使用向け。./heic2jpg.py FILE...）。添付ツールはアップロード時に HEIC を自動変換するため、アップロード前に HEIC のフレームをビジョン処理に渡す場合にのみ必要です。

どちらも pillow-heif に依存しており、libheif が同梱されているため、システムパッケージのインストールは不要です。

セキュリティ

• API キーの取り扱い。 クローンを使うワークフローでは、キーは .env に保存されます。このファイルは gitignore の対象であり、パーミッションを 600 に設定してください（chmod 600 .env）。キーをコミットしないでください。uvx を使うワークフローでは、キーを MCP クライアントの設定経由で渡します。このファイルも秘密情報として扱ってください。
• キーのローテーション。 Homebox の HBOX_AUTH_API_KEY_PEPPER をローテーションすると、発行済みのキーはすべて無効になります。新しいキーを発行し、設定を更新してください。
• 確認が必要な削除。 4つすべての削除ツールでは、confirm が対象の名前と完全に一致する必要があり、MCP の destructiveHint アノテーションが付いています。そのため、適切に動作するクライアントは、破壊的な呼び出しの前に確認を求めます。
• リモートの Homebox インスタンスには HTTPS を使用してください。API キーはすべてのリクエストで Authorization ヘッダーに含めて送信されます。

開発

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 .

サーバーは、PEP 723 のインライン依存関係を含む単一のモジュール（homebox_mcp.py）で構成されています。セットアップとプルリクエストに関する要件は CONTRIBUTING.md を、リリースノートは CHANGELOG.md を参照してください。

ライセンス

MIT © Dan Gahagan