AI导哈

Grocy MCP服务器

Grocy MCP是一个基于Grocy REST API的MCP服务器，为家庭库存管理、购物清单、食谱、家务和任务提供结构化工具。

  • by daniel-iliesh
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 daniel-iliesh/grocy-mcp

使用说明

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=<token>
    • 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检验员测试

  1. 启动服务器：

    uv run python server.py

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

    • http://localhost:8010/sse

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

  4. 尝试调用以下工具：

    • get_stock
    • get_stock_volatile
    • get_shopping_list
    • get_recipes
    • get_chores
    • get_tasks

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

注意事项和限制

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

相关 MCP