Hermes Grocy MCP

Grocy MCP

一个适用于 Grocy 的模型上下文协议（MCP）服务。Grocy 是一款可自托管的家庭 ERP，用于管理杂货、库存、家务、电池、食谱、任务和购物清单。

此服务专注于通过通用 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	Grocy 基础 URL，可带或不带 /api
GROCY_API_KEY	对公开／演示只读实例为否，对私有实例／写入访问为是	未设置	作为 GROCY-API-KEY 发送的 Grocy API 密钥
GROCY_TIMEOUT	否	20	HTTP 超时时间，单位为秒

Grocy API 密钥可在 Grocy 的 Manage API keys 下管理。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	获取单个产品对象
grocy_lookup_product_by_barcode	查询条形码／Grocycode
grocy_stock_overview	当前库存条目
grocy_volatile_stock	即将到期、已过期或缺失的产品
grocy_product_stock_details	单个产品的详细库存状态
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 客户端环境配置或密钥管理器中，切勿将其提交到源代码管理。