Grocy MCP家庭助理服务器

Grocy MCP是一个MCP（模型上下文协议）服务器，它在 Grocy REST API，针对以下工具的使用进行了优化 MCP检查员 以及LLM IDE集成。

它为以下方面提供了结构化工具：

库存管理
购物单
食谱
家务
任务

…加上一些便利助手（例如基于条形码的库存操作和库存调整）。

所有呼叫都通过具有基于WebSocket的身份验证的家庭助理入口URL路由，并通过 服务器发送的事件（SSE） 在港口 8010.

______________________________________________________________________

建筑与交通

MCP框架: mcp.server.fastmcp.FastMCP
运输上海证券交易所mcp.sse_app() 包装在Starlette应用程序中）
端口: 8010
跨域资源共享：完全打开(allow_origins=["*"])用于基于浏览器的MCP检查器
HTTP客户端: httpx.AsyncClient
认证+入口:

- 使用家庭助理WebSocket会话(ha_session.py)请求一个短暂的生命 ingress_session 每60秒发一次代币。 - 该令牌以cookie的形式发送： Cookie: ingress_session= - Grocy API密钥通过 GROCY-API-KEY 头球

MCP服务器本身 不存储任何凭据；它从环境变量中读取它们/ .env 通过 pydantic-settings.

______________________________________________________________________

配置

配置定义见 settings.py 并从环境中加载/ .env:

GROCY_API_URL\

Grocy API的基本URL，包括入口路径，例如： http://homeassistant.local:9192/api/hassio_ingress/XXXX/api

GROCY_API_KEY\

Grocy API密钥。可以在Grocy UI中进行管理。

HA_TOKEN\

用于WebSocket身份验证的长期家庭助理访问令牌。

示例 .env:

GROCY_API_URL=http://homeassistant.local:9192/api/hassio_ingress/XXXX/api
GROCY_API_KEY=your-grocy-api-key
HA_TOKEN=your-home-assistant-token

这 Settings 上课中 settings.py 自动读取 .env 当存在时。

______________________________________________________________________

运行MCP服务器

从项目根：

uv run python server.py

在成功的创业中，你应该看到这样的东西：

Starting Grocy MCP Server (SSE) with CORS enabled...
Server running at: http://localhost:8010/sse

然后，您可以指向 MCP检查员 （或任何兼容MCP的客户端）在SSE URL：

网址： http://localhost:8010/sse

所有Grocy工具将显示在工具面板上显示了它们的文档字符串和类型信息。

______________________________________________________________________

工具概览

工具总数（基线）： 27\ 另外还有几个助手（基于条形码的操作、转移、库存调整）。

1.库存管理

get_stock()\

返回当前库存的所有产品，包括数量和下次到期日期。\ 格罗西终点： GET /stock.

get_stock_volatile()\

返回波动性股票：即将到期、过期、丢失（低于最低库存）和到期产品。\ 格罗西终点： GET /stock/volatile.

get_product_details(product_id: int)\

单个产品的详细信息：数量、有效期、位置等。\ 格罗西终点： GET /stock/products/{productId}.

search_products(query: str)\

方便按名称搜索所有产品。\ 实施： GET /objects/products 并打开内存过滤器 name.

add_stock(product_id: int, amount: float, best_before_date: str | None = None, price: float | None = None)\

为产品添加库存（例如购物后）。\ 用途 transaction_type="purchase".\ 格罗西终点： POST /stock/products/{productId}/add.

consume_stock(product_id: int, amount: float, spoiled: bool = False)\

消耗或损坏库存中的产品。\ 用途 transaction_type="consume".\ 格罗西终点： POST /stock/products/{productId}/consume.

其他库存助手

这些是建立在Grocy更先进的股票端点之上的：

transfer_stock(product_id: int, amount: float, location_id_from: int, location_id_to: int, stock_entry_id: str | None = None)\

将产品从一个位置转移到另一个位置。\ 格罗西终点： POST /stock/products/{productId}/transfer.

inventory_product(product_id: int, new_amount: float, best_before_date: str | None = None, location_id: int | None = None, price: float | None = None, note: str | None = None)\

设置 *绝对的* 产品的库存盘点（根据需要添加或删除）。\ 格罗西终点： POST /stock/products/{productId}/inventory.

open_product(product_id: int, amount: float = 1.0)\

将一个或多个单元标记为打开。\ 格罗西终点： POST /stock/products/{productId}/open.

2.基于条形码的库存操作

这些对于“扫描购买”或快速消费工作流程特别方便。

get_product_by_barcode(barcode: str)\

通过条形码查找产品详细信息。\ 格罗西终点： GET /stock/products/by-barcode/{barcode}.

add_stock_by_barcode(barcode: str, amount: float, best_before_date: str | None = None, price: float | None = None, location_id: int | None = None)\

通过条形码为产品添加库存（例如在家扫描杂货后）。\ 用途 transaction_type="purchase".\ 格罗西终点： POST /stock/products/by-barcode/{barcode}/add.

consume_stock_by_barcode(barcode: str, amount: float, spoiled: bool = False, location_id: int | None = None)\

通过条形码消耗或销毁产品的库存。\ 用途 transaction_type="consume".\ 格罗西终点： POST /stock/products/by-barcode/{barcode}/consume.

transfer_stock_by_barcode(barcode: str, amount: float, location_id_from: int, location_id_to: int, stock_entry_id: str | None = None)\

在不同地点之间转移条形码识别的产品。\ 格罗西终点： POST /stock/products/by-barcode/{barcode}/transfer.

inventory_product_by_barcode(barcode: str, new_amount: float, best_before_date: str | None = None, location_id: int | None = None, price: float | None = None)\

按条形码清点产品（设置绝对数量）。\ 格罗西终点： POST /stock/products/by-barcode/{barcode}/inventory.

external_barcode_lookup(barcode: str, add: bool = False)\

使用Grocy的外部条形码查找插件来识别未知的条形码。当 add=true 在支持下，Grocy可以自动创建产品。\ 格罗西终点： GET /stock/barcodes/external-lookup/{barcode}.

3.产品创建和条形码

create_simple_product(name: str, qu_id_stock: int, qu_id_purchase: int | None = None, location_id: int | None = None, description: str | None = None)\

使用最常用的字段创建新产品。如果 qu_id_purchase 如果省略，则默认为 qu_id_stock.\ 格罗西终点： POST /objects/products.

add_barcode_to_product(product_id: int, barcode: str, note: str | None = None)\

将条形码附加到现有产品上。\ 格罗西终点： POST /objects/product_barcodes.

delete_product_barcode(barcode_id: int)\

按id删除产品条形码行。\ 格罗西终点： DELETE /objects/product_barcodes/{id}.

update_product(product_id: int, ...)\

更新现有产品的选定字段（名称、描述、位置、单位、最小库存、产品组）。\ 格罗西终点： PUT /objects/products/{id}.

delete_product(product_id: int)\

按id删除产品。请小心使用，因为它会删除产品定义。\ 格罗西终点： DELETE /objects/products/{id}.

create_quantity_unit(name: str, name_plural: str | None = None, description: str | None = None)\

创建一个新的数量单位（例如，当您引入一种尚未在Grocy中使用的新单位时）。\ 格罗西终点： POST /objects/quantity_units.

4.参考数据（模型通常需要的ID）

get_quantity_units()\

列出所有数量单位。使用此功能发现有效 qu_id_stock 为了 create_simple_product.\ 格罗西终点： GET /objects/quantity_units.

delete_quantity_unit(qu_id: int)\

按id删除数量单位。仅当您确定现有产品没有使用它时才执行此操作。\ 格罗西终点： DELETE /objects/quantity_units/{id}.

get_locations()\

列出所有位置。使用此功能发现有效 location_id 产品和库存操作的价值。\ 格罗西终点： GET /objects/locations.

delete_location(location_id: int)\

按id删除位置。\ 格罗西终点： DELETE /objects/locations/{id}.

get_shopping_lists()\

列出所有购物清单。用这个来选择正确的 shopping_list_id.\ 格罗西终点： GET /objects/shopping_lists.

delete_shopping_list(list_id: int)\

删除购物清单定义（而不仅仅是其项目）。\ 格罗西终点： DELETE /objects/shopping_lists/{id}.

get_product_groups()\

列出所有产品组。直接与Grocy合作时，有助于对产品进行分类。\ 格罗西终点： GET /objects/product_groups.

delete_product_group(group_id: int)\

按id删除产品组。\ 格罗西终点： DELETE /objects/product_groups/{id}.

undo_stock_booking(booking_id: int)\

当记录错误时，撤消单个库存预订。\ 格罗西终点： POST /stock/bookings/{bookingId}/undo.

undo_stock_transaction(transaction_id: str)\

按交易id撤消整个股票交易（多个预订）。\ 格罗西终点： POST /stock/transactions/{transactionId}/undo.

5.购物清单

get_shopping_list()\

获取当前购物清单中的商品。\ 格罗西终点： GET /objects/shopping_list.

add_to_shopping_list(product_id: int, amount: float = 1.0, shopping_list_id: int = 1, note: str | None = None)\

将产品添加到购物清单中。\ 格罗西终点： POST /objects/shopping_list.

remove_from_shopping_list(item_id: int)\

从购物清单中删除特定项目。\ 格罗西终点： DELETE /objects/shopping_list/{id}.

clear_shopping_list(shopping_list_id: int = 1)\

清除购物清单中的所有项目。\ 格罗西终点： POST /stock/shoppinglist/{shoppingListId}/clear.

add_missing_products_to_shopping_list()\

自动将低于最低库存的所有产品添加到默认购物清单中。\ 格罗西终点： POST /stock/shoppinglist/add-missing-products.

6.食谱

get_recipes()\

列出所有食谱。\ 格罗西终点： GET /objects/recipes.

get_recipe(recipe_id: int)\

详细的食谱视图，包括配料和说明。\ 格罗西终点： GET /objects/recipes/{recipeId}.

delete_recipe(recipe_id: int)\

按id删除配方。\ 格罗西终点： DELETE /objects/recipes/{id}.

add_recipe_to_shopping_list(recipe_id: int)\

将给定食谱中缺少的配料添加到购物清单中。\ 格罗西终点： POST /recipes/{recipeId}/add-not-fulfilled-products-to-shoppinglist.

consume_recipe(recipe_id: int)\

从库存中消耗食谱所需的所有配料。\ 格罗西终点： POST /recipes/{recipeId}/consume.

get_recipe_fulfillment(recipe_id: int)\

获取特定配方的库存履行信息（哪些成分缺失或部分可用）。\ 格罗西终点： GET /recipes/{recipeId}/fulfillment.

get_all_recipes_fulfillment()\

获取所有食谱的履行信息，以回答“我现在可以做什么？”等问题。\ 格罗西终点： GET /recipes/fulfillment.

7.合唱

get_chores()\

列出所有杂务，包括下一次估计的执行时间。\ 格罗西终点： GET /chores.

get_chore(chore_id: int)\

获取单个杂务的详细信息。\ 格罗西终点： GET /chores/{choreId}.

track_chore(chore_id: int, tracked_time: str | None = None, done_by: int | None = None)\

将一项杂务标记为已完成，可以选择指定是谁做的以及在什么时间做的。\ 格罗西终点： POST /chores/{choreId}/execute.

undo_chore_execution(execution_id: int)\

当之前跟踪的杂务执行被错误记录时，撤消该执行。\ 格罗西终点： POST /chores/executions/{executionId}/undo.

delete_chore(chore_id: int)\

按id删除杂务定义。\ 格罗西终点： DELETE /objects/chores/{id}.

8.任务

get_tasks()\

列出所有任务。\ 格罗西终点： GET /tasks.

create_task(name: str, description: str | None = None, due_date: str | None = None)\

创建新任务。\ 格罗西终点： POST /objects/tasks.

update_task(task_id: int, ...)\

更新现有任务的选定字段（名称、描述、截止日期）。\ 格罗西终点： PUT /objects/tasks/{id}.

complete_task(task_id: int)\

将任务标记为已完成。\ 格罗西终点： POST /tasks/{taskId}/complete.

delete_task(task_id: int)\

按id删除任务。\ 格罗西终点： DELETE /objects/tasks/{taskId}.

______________________________________________________________________

使用示例

库存管理

# Check expiring products
volatile = get_stock_volatile()

# Add groceries after shopping (by product id)
add_stock(
    product_id=42,
    amount=3,
    best_before_date="2025-12-31",
    price=2.99,
)

# Use milk from stock
consume_stock(product_id=10, amount=1)

基于条形码的工作流

# Scan a product to see details
product = get_product_by_barcode(barcode="0123456789012")

# Purchase items by scanning them
add_stock_by_barcode(
    barcode="0123456789012",
    amount=2,
    best_before_date="2025-06-01",
    price=1.49,
)

# Consume by barcode
consume_stock_by_barcode(barcode="0123456789012", amount=1)

购物清单和食谱

# Auto‑add missing products
add_missing_products_to_shopping_list()

# Clear the default shopping list
clear_shopping_list()

# Plan dinner
recipe = get_recipe(recipe_id=5)
add_recipe_to_shopping_list(recipe_id=5)

# After cooking
consume_recipe(recipe_id=5)

______________________________________________________________________

MCP检验员测试

启动服务器：

   uv run python server.py

在MCP检查器中，添加一个新的SSE服务器，指向：

- http://localhost:8010/sse

验证所有Grocy工具是否显示在工具部分。

尝试调用以下工具：

- get_stock - get_stock_volatile - get_shopping_list - get_recipes - get_chores - get_tasks

如果您在Grocy中配置了条形码，则可以选择测试条形码工具。

______________________________________________________________________

注意事项和限制

此MCP服务器假定 Grocy在Home Assistant入口后面跑；直接Grocy URL可能需要调整 GROCY_API_URL 以及身份验证逻辑。
所有工具都是Grocy官方API的薄包装；错误和验证直接来自Grocy。
对于未作为显式工具公开的高级/自定义操作，您仍然可以将这些构建块与LLM推理相结合。

Grocy MCP

快速接入

详细介绍

Grocy MCP家庭助理服务器

建筑与交通

配置

运行MCP服务器

工具概览

1.库存管理

其他库存助手

2.基于条形码的库存操作

3.产品创建和条形码

4.参考数据（模型通常需要的ID）

5.购物清单

6.食谱

7.合唱

8.任务

使用示例

库存管理

基于条形码的工作流

购物清单和食谱

MCP检验员测试

注意事项和限制

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP