HomeBoxMCP

自宅の在庫に話しかける。 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."

16 個のツール、1 つのファイル、ランタイム依存ゼロ — 必要なのは Node 22 と node:http だけです。Docker の後ろに置いて、あとは忘れていてください。

これが選ばれる理由

• 読み取り と 書き込み。 第三者が公開する読み取り専用の homebox-mcp とは混同しないでください。こちらは作成、更新、移動、削除、ファイル添付ができます。

• Homebox v0.26.x 向けに構築。 アイテムとロケーションが "entities" として統一され、ラベルは "tags" に切り替わった entity API を対象にしています。

• ステートレスなストリーム HTTP。 セッションストアもデータベースもサイドカーもありません。いつでも再起動してください。

• 変に失敗しない、はっきり失敗します。 --doctor は、サーバーが最初のリクエストを受け入れる前に Homebox への接続を検証し、容量オーバーのアップロードは不透明な 422 ではなく実サイズ付きで拒否されます。

Related MCP server: Homebox MCP Server

クイックスタート

公開済みイメージを pull します:

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 は、Homebox の URL に到達できることと、さらに 認証情報が実際に機能することを確認し、だめだった場合は1行の理由を添えて非ゼロで終了します。

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 URL を指定して追加するか、公開されたら Community Apps からインストールしてください。config と inbox のパスは自分が管理する共有フォルダにし、LAN の外からもコンテナに到達してもらうなら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-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

添付ファイル、そしてインボックスがある理由

MCP ツールと呼び出しは JSON で、バイナリをそのまま運べません。10 MB の領収書を base64 としてインライン化すると、ファイルを 1 つ動かすだけでモデルの前後関係を約 13 MB 分消費してしまいます。そこで、ファイルは読み取り専用のインボックスのマウント経由で HomeBoxMCP に届ける仕組みです。ファイルをインボックスに置き、ファイル名で添付しる、という形です。パスはインボックスを基準に解決され、抜け出そうなどするものは拒否されます — ../../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 を参照してください。