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 分