Hermes Grocy MCP

io.github.rusty4444由 GitHub 帳號 rusty4444 發布v0.2.1更新於 Oct 24, 2026

MCP server for Grocy household ERP inventory and shopping workflows.

已驗證STDIO僅桌面效率與工作流商業與電商

概覽

AI 產生的概覽

一個本機 MCP 伺服器，讓助理連接自架的 Grocy 家庭 ERP，管理商品、庫存、購物清單、家事和任務。

可以做什麼
查看 Grocy 系統與版本狀態，列出、搜尋或取得商品，並可依條碼或 Grocycode 查找。讀取目前庫存、易變庫存、單一商品的庫存詳情和庫存項目。列出購物清單及其項目，並新增或移除商品及數量。增加、消耗或設定商品庫存數量。列出、建立和更新通用 Grocy 實體，並從 JSON 設定自訂欄位。列出含下次到期時間的家事、執行家事，以及列出任務。
適用情境
當你自架 Grocy，並希望助理回答庫存、購物清單、家事和任務相關問題，或完成日常家庭庫存變更而不必手寫 REST 呼叫時適用。
執行需求
以 Python 套件形式在本機執行（可透過 pipx 或 uvx 安裝）。需要 GROCY_BASE_URL 指定 Grocy 位址（預設指向公開示範實例）；私有實例或寫入操作還需在 GROCY_API_KEY 中提供 API 金鑰。可選 GROCY_TIMEOUT 設定 HTTP 逾時。需要能連線至 Grocy 實例的網路。
安裝前請注意
許多工具會直接修改 Grocy 資料：增減庫存、調整盤點、編輯購物清單、建立或更新通用實體、修改自訂欄位以及執行家事。涉及寫入時應指向私有實例，而非共用的公開示範。GROCY_API_KEY 應保存在用戶端環境設定或密鑰管理器中，不要放入原始碼倉庫。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Hermes Grocy MCP，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Grocy MCP

A Model Context Protocol (MCP) server for Grocy, the self-hosted household ERP for groceries, inventory, chores, batteries, recipes, tasks, and shopping lists.

This server focuses on AI-friendly household operations that are awkward through generic REST clients:

  • Inspect Grocy system/version status
  • List, search, and inspect products
  • Read current stock, volatile stock, product stock details, and individual stock entries
  • List current shopping list items and add/remove products from shopping lists
  • Look up products by barcode/Grocycode
  • List and inspect any /api/objects/{entity} entity
  • Create/update generic entity objects from JSON
  • Add, consume, and inventory product stock
  • Add/remove product amounts from shopping lists

Why this exists

Grocy has a strong REST API, but MCP coverage is sparse and usually either incomplete or tightly coupled to one client's workflow. This package gives Hermes, Claude Desktop, Cursor, and other MCP clients a small, explicit, documented tool surface.

Installation

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

Or from a checkout:

bash
python -m venv .venvsource .venv/bin/activatepip install -e .

Configuration

The server reads configuration from environment variables:

VariableRequiredDefaultDescription
GROCY_BASE_URLNohttps://demo.grocy.infoGrocy base URL, with or without /api
GROCY_API_KEYNo for public/demo read-only instances, yes for private/write accessunsetGrocy API key sent as GROCY-API-KEY
GROCY_TIMEOUTNo20HTTP timeout in seconds

Grocy API keys are managed in Grocy under Manage API keys. The API accepts the GROCY-API-KEY header.

MCP client config

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

Tools

ToolPurpose
grocy_system_infoGrocy version and runtime details
grocy_list_productsList configured products
grocy_search_productsSearch products by name/description
grocy_get_productFetch one product object
grocy_lookup_product_by_barcodeResolve a barcode/Grocycode
grocy_stock_overviewCurrent stock rows
grocy_volatile_stockDue, overdue, expired, or missing products
grocy_product_stock_detailsDetailed stock state for one product
grocy_product_stock_entriesIndividual stock entries in next-use order
grocy_common_entitiesCommon generic entity names useful with CRUD tools
grocy_list_shopping_listsConfigured shopping lists
grocy_list_shopping_list_itemsCurrent shopping list rows, optionally filtered by list id
grocy_list_entityList any generic Grocy entity
grocy_get_entity_objectFetch any generic entity object
grocy_create_entity_objectPOST a generic entity object from JSON
grocy_update_entity_objectPUT a generic entity object from JSON
grocy_add_stockAdd product amount to stock
grocy_consume_stockConsume/remove product amount from stock
grocy_inventory_productSet product inventory amount
grocy_add_product_to_shopping_listAdd a product to a shopping list
grocy_remove_product_from_shopping_listRemove a product from a shopping list
grocy_set_userfieldsSet userfield values on an entity object
grocy_list_choresList chores including computed next-due times
grocy_execute_choreExecute (mark done) a chore, optionally backdated
grocy_list_tasksList tasks

Development and validation

bash
python -m venv .venvsource .venv/bin/activatepip install -e '.[dev]'ruff check .pytestpython scripts/live_readonly_test.py

The live read-only test defaults to https://demo.grocy.info, avoiding mutations on shared infrastructure. It has been validated against Grocy API 4.6.0. Use a private Grocy instance plus GROCY_API_KEY for write-path testing.

Safety

Write-capable tools directly mutate Grocy data. Prefer read-only tools when using public demos. Keep GROCY_API_KEY in MCP client environment config or a secret manager, never in source control.

來源：README.md，提交 1961e6e

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v0.2.1最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分