Hermes Grocy MCP

Grocy MCP

食料品、在庫、家事、電池、レシピ、タスク、買い物リストを管理するセルフホスト可能な家庭向け ERP、Grocy 用の Model Context Protocol（MCP）サーバーです。

このサーバーは、汎用的な REST クライアントでは扱いにくい、AI に適した家庭内の操作に重点を置いています。

• Grocy のシステム／バージョンの状態を確認する
• 商品を一覧表示、検索、確認する
• 現在の在庫、変動在庫、商品在庫の詳細、個々の在庫エントリーを読み取る
• 現在の買い物リスト項目を一覧表示し、買い物リストに商品を追加／削除する
• バーコード／Grocycode で商品を検索する
• 任意の /api/objects/{entity} エンティティを一覧表示、確認する
• JSON から汎用エンティティオブジェクトを作成／更新する
• 商品在庫を追加、消費、棚卸しする
• 買い物リストの商品数量を追加／削除する

これが作られた理由

Grocy には優れた REST API がありますが、MCP による対応はまばらで、通常は不完全か、特定のクライアントのワークフローに強く依存しています。このパッケージは、Hermes、Claude Desktop、Cursor などの MCP クライアント向けに、小規模で明確に定義され、ドキュメント化されたツール群を提供します。

インストール

pipx install git+https://github.com/rusty4444/grocy-mcp.git

または、チェックアウトしたソースからインストールします。

python -m venv .venv
source .venv/bin/activate
pip install -e .

設定

サーバーは環境変数から設定を読み込みます。

変数	必須	デフォルト	説明
GROCY_BASE_URL	いいえ	https://demo.grocy.info	/api の有無を問わない Grocy のベース URL
GROCY_API_KEY	公開／デモ用の読み取り専用インスタンスでは不要、プライベート環境／書き込みアクセスでは必要	未設定	GROCY-API-KEY として送信する Grocy API キー
GROCY_TIMEOUT	いいえ	20	HTTP タイムアウト（秒）

Grocy API キーは、Grocy の API キーの管理 で管理します。API は GROCY-API-KEY ヘッダーを受け付けます。

MCP クライアントの設定

{
  "mcpServers": {
    "grocy": {
      "command": "grocy-mcp",
      "env": {
        "GROCY_BASE_URL": "https://grocy.example.com",
        "GROCY_API_KEY": "your-api-key"
      }
    }
  }
}

ツール

ツール	目的
grocy_system_info	Grocy のバージョンと実行時の詳細
grocy_list_products	登録済みの商品を一覧表示する
grocy_search_products	商品名／説明で商品を検索する
grocy_get_product	1 つの商品オブジェクトを取得する
grocy_lookup_product_by_barcode	バーコード／Grocycode を特定する
grocy_stock_overview	現在の在庫行
grocy_volatile_stock	期限間近、期限超過、期限切れ、または不足している商品
grocy_product_stock_details	1 つの商品の詳細な在庫状況
grocy_product_stock_entries	次に使用する順に並んだ個々の在庫エントリー
grocy_common_entities	CRUD ツールで使用できる一般的な汎用エンティティ名
grocy_list_shopping_lists	登録済みの買い物リスト
grocy_list_shopping_list_items	現在の買い物リスト行。必要に応じてリスト ID で絞り込み可能
grocy_list_entity	任意の汎用 Grocy エンティティを一覧表示する
grocy_get_entity_object	任意の汎用エンティティオブジェクトを取得する
grocy_create_entity_object	JSON から汎用エンティティオブジェクトを POST する
grocy_update_entity_object	JSON から汎用エンティティオブジェクトを PUT する
grocy_add_stock	商品の数量を在庫に追加する
grocy_consume_stock	商品の数量を在庫から消費／削除する
grocy_inventory_product	商品の在庫数量を設定する
grocy_add_product_to_shopping_list	買い物リストに商品を追加する
grocy_remove_product_from_shopping_list	買い物リストから商品を削除する
grocy_set_userfields	エンティティオブジェクトのユーザーフィールド値を設定する
grocy_list_chores	算出された次回期限を含む家事を一覧表示する
grocy_execute_chore	家事を実行（完了としてマーク）する。必要に応じて過去の日付を指定可能
grocy_list_tasks	タスクを一覧表示する

開発と検証

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
ruff check .
pytest
python scripts/live_readonly_test.py

ライブの読み取り専用テストは、共有インフラストラクチャへの変更を避けるため、デフォルトで https://demo.grocy.info を使用します。Grocy API 4.6.0 に対して検証済みです。書き込み経路のテストには、プライベートな Grocy インスタンスと GROCY_API_KEY を使用してください。

安全性

書き込み可能なツールは、Grocy のデータを直接変更します。公開デモを使用する際は、読み取り専用ツールを優先してください。GROCY_API_KEY は MCP クライアントの環境設定またはシークレットマネージャーに保管し、ソース管理には決して含めないでください。