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推理相结合。