grocy-mcp
Provides tools for interacting with a self-hosted Grocy instance via its REST API, covering all 74 paths (87 operations): generic entity CRUD for products, recipes, chores, tasks, batteries, equipment, meal plans, shopping lists, userobjects and userfields, plus stock management (add, consume, transfer, inventory, open, merge, barcode lookup), recipe fulfillment and consumption, chore and battery tracking, task completion, files, users/permissions, and system endpoints.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@grocy-mcp Add milk and eggs to my shopping list"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
grocy-mcp (Grocy MCP connector)
MCP connector for a Grocy instance. It speaks the Grocy REST API over stdio and over stateless Streamable HTTP on localhost.
Grocy is MIT software. Self-host it. This connector does not grant any right to the Grocy name, and it does not imply endorsement.
This connector is MIT. It is a BYO-key client for your own instance.
The connector covers all 74 paths (87 operations) in grocy.openapi.json. Stock mutations, chores, tasks, batteries, recipes, meal plan, equipment, userobjects, userfields, files, users, and system endpoints are included.
Setup
npm install
npm run ci
npm start
npm run start:httpnpm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication. Keep it on localhost.
Create an API key in Grocy under Manage API keys. The connector sends it as GROCY-API-KEY and never prints it.
{
"mcpServers": {
"grocy": {
"command": "node",
"args": ["/workspace/connectors/grocy/dist/index.js"],
"env": {
"GROCY_URL": "http://127.0.0.1:5056",
"GROCY_API_KEY": "...",
"GROCY_ALLOW_WRITES": "false",
"GROCY_CONTACT": "you@example.com"
}
}
}
}A trailing /api on GROCY_URL is stripped.
Docker (HTTP, no authentication, localhost only):
docker build -t grocy-mcp .
docker run -p 3000:3000 \
-e GROCY_URL=http://host.docker.internal:5056 \
-e GROCY_API_KEY=... \
grocy-mcpDo not put the API key in the image.
Related MCP server: kitchenowl-mcp
Tools
Generic entity CRUD (grocy_objects_*) is how you create and edit products, recipes, chores, tasks, batteries, equipment, meal plan rows, shopping lists, userobjects, userfields, and the other ExposedEntity values.
Tool | Call |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| product stock reads plus |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| shopping list add-missing, add-overdue, add-expired, clear, add_product, remove_product |
| get or undo a stock booking |
| get or undo a stock transaction |
|
|
| one recipe or all recipes |
|
|
| add missing recipe products to a shopping list |
|
|
| print a recipe Grocycode |
|
|
|
|
|
|
| undo a chore execution |
| recalculate next assignments |
| print a chore Grocycode |
| merge two chores |
|
|
|
|
| track a charge cycle |
| undo a charge cycle |
| print a battery Grocycode |
|
|
| complete a task |
| mark a task not done |
|
|
|
|
| thermal print a shopping list |
grocy_files_* takes the plain file_name. The connector base64-encodes it for Grocy.
Environment
Variable | Default | Role |
|
| Instance origin. No userinfo, query, or hash. A trailing |
| unset | Required for an upstream call. At least 8 characters. Never printed |
| off | The literal |
|
| Contact inside the User-Agent. Must not contain the API key |
|
| Local sliding-window cap |
|
| TTL for successful reads. |
|
| Upstream timeout |
|
|
|
|
| HTTP listen port |
Invalid values are reported by field name and issue code. The rejected value is not included.
Safety
A write tool returns a dry-run preview when confirm is omitted. The preview is the method, path, query, and body that would be sent.
confirm must be the boolean true. false and the string "true" are rejected.
When confirm is true and GROCY_ALLOW_WRITES is not true, the tool still returns the preview, sets blocked to true, and does not call the instance.
Writes include POST, PUT, DELETE, stock add/consume/transfer/inventory/open/undo, chore execute, file upload and delete, printlabel, thermal print, and barcode lookup with add=true.
The API key is removed from tool results, error text, and logs, including its URL-encoded form. It is refused in the query string, the base URL, the User-Agent, and a JSON request body. Password fields are redacted. Absolute server filesystem paths are dropped.
Licence
Grocy is MIT (https://github.com/grocy/grocy). This connector is MIT.
License
MIT, see LICENSE. This is an independent, unofficial connector and is not endorsed by the Grocy project or its owners.
grocy.openapi.json is from grocy/grocy (MIT, Copyright (c) Bernd Bestel).
Available Tools
62 toolsgrocy_barcode_lookupA
External barcode lookup. GET /api/stock/barcodes/external-lookup/{barcode}. add=true also creates the product and needs confirm.
Inputs: barcode (required), add, confirm.
grocy_batteries_listARead-only
All batteries with next estimated charge time. GET /api/batteries.
Inputs: no named parameters.
grocy_battery_chargeA
Track a battery charge cycle. POST /api/batteries/{batteryId}/charge. Omit confirm for a dry-run.
Inputs: battery_id (required), confirm, tracked_time.
grocy_battery_getBRead-only
Details of one battery. GET /api/batteries/{batteryId}.
Inputs: battery_id (required).
grocy_battery_printlabelA
Print the Grocycode label for a battery. GET /api/batteries/{batteryId}/printlabel. Omit confirm for a dry-run.
Inputs: battery_id (required), confirm.
grocy_battery_undo_chargeA
Undo a battery charge cycle. POST /api/batteries/charge-cycles/{chargeCycleId}/undo. Omit confirm for a dry-run.
Inputs: charge_cycle_id (required), confirm.
grocy_calendar_icalARead-only
Household calendar as iCal text. GET /api/calendar/ical.
Inputs: no named parameters.
grocy_calendar_sharing_linkBRead-only
Public sharing link for the iCal calendar. GET /api/calendar/ical/sharing-link.
Inputs: no named parameters.
grocy_chore_executeA
Track a chore execution. POST /api/chores/{choreId}/execute. Omit confirm for a dry-run.
Inputs: chore_id (required), confirm, done_by, skipped, +1 more.
grocy_chore_getCRead-only
Details of one chore. GET /api/chores/{choreId}.
Inputs: chore_id (required).
grocy_chore_mergeADestructiveIdempotent
Merge two chores. POST /api/chores/{choreIdToKeep}/merge/{choreIdToRemove}. Omit confirm for a dry-run.
Inputs: chore_id_to_keep (required), chore_id_to_remove (required), confirm.
grocy_chore_printlabelA
Print the Grocycode label for a chore. GET /api/chores/{choreId}/printlabel. Omit confirm for a dry-run.
Inputs: chore_id (required), confirm.
grocy_chores_calculate_assignmentsB
Recalculate next chore user assignments. POST /api/chores/executions/calculate-next-assignments. Omit confirm for a dry-run.
Inputs: confirm, chore_id.
grocy_chores_listBRead-only
All chores with next estimated execution. GET /api/chores.
Inputs: no named parameters.
grocy_chore_undo_executionA
Undo a chore execution. POST /api/chores/executions/{executionId}/undo. Omit confirm for a dry-run.
Inputs: execution_id (required), confirm.
grocy_current_userARead-only
The authenticated Grocy user. GET /api/user. Passwords are redacted.
Inputs: no named parameters.
grocy_files_deleteADestructiveIdempotent
Delete a file. DELETE /api/files/{group}/{fileName}. Omit confirm for a dry-run.
Inputs: group (required), file_name (required), confirm.
grocy_files_getBRead-only
Download a file. GET /api/files/{group}/{fileName}. file_name is the plain name. The connector base64-encodes it. Small files return text or base64. Large files return size only. Server paths are omitted.
Inputs: group (required), file_name (required), best_fit_width, force_serve_as, +1 more.
grocy_files_putAIdempotent
Upload a file as application/octet-stream. PUT /api/files/{group}/{fileName}. content_base64 is the file bytes. Omit confirm for a dry-run.
Inputs: group (required), file_name (required), content_base64 (required), confirm.
grocy_objects_createA
Create one Grocy object. POST /api/objects/{entity}. fields is the entity JSON. Omit confirm for a dry-run.
Inputs: entity (required), fields (required), confirm.
grocy_objects_deleteADestructiveIdempotent
Delete one Grocy object. DELETE /api/objects/{entity}/{objectId}. Omit confirm for a dry-run.
Inputs: entity (required), object_id (required), confirm.
grocy_objects_getBRead-only
Get one Grocy object. GET /api/objects/{entity}/{objectId}.
Inputs: entity (required), object_id (required).
grocy_objects_listBRead-only
List objects of a Grocy entity. GET /api/objects/{entity}. entity covers products, recipes, chores, tasks, batteries, equipment, meal_plan, userobjects, userfields, shopping_lists, and other ExposedEntity values. Optional query[], order, limit, offset.
Inputs: entity (required), limit, order, query, +1 more.
grocy_objects_updateAIdempotent
Edit one Grocy object. PUT /api/objects/{entity}/{objectId}. Omit confirm for a dry-run.
Inputs: entity (required), fields (required), object_id (required), confirm.
grocy_print_shoppinglistB
Print a shopping list on the configured thermal printer. GET /api/print/shoppinglist/thermal. Omit confirm for a dry-run.
Inputs: list, confirm, print_header.
grocy_recipe_add_missing_to_shoppinglistB
Add missing recipe products to the shopping list. POST /api/recipes/{recipeId}/add-not-fulfilled-products-to-shoppinglist. Omit confirm for a dry-run.
Inputs: recipe_id (required), confirm, excluded_product_ids.
grocy_recipe_consumeA
Consume in-stock ingredients of a recipe. POST /api/recipes/{recipeId}/consume. Omit confirm for a dry-run.
Inputs: recipe_id (required), confirm.
grocy_recipe_copyA
Copy a recipe. POST /api/recipes/{recipeId}/copy. Omit confirm for a dry-run.
Inputs: recipe_id (required), confirm.
grocy_recipe_fulfillmentCRead-only
Recipe stock fulfillment. action one is GET /api/recipes/{recipeId}/fulfillment. all is GET /api/recipes/fulfillment.
Inputs: action (required), query, recipe_id.
grocy_recipe_printlabelB
Print the Grocycode label for a recipe. GET /api/recipes/{recipeId}/printlabel. Omit confirm for a dry-run.
Inputs: recipe_id (required), confirm.
grocy_shopping_listBDestructiveIdempotent
Shopping list helpers. action add_missing, add_overdue, add_expired, clear, add_product, remove_product. All writes. Omit confirm for a dry-run.
Inputs: action (required), note, qu_id, confirm, +4 more.
grocy_stock_addB
Add amount of a product to stock. POST /api/stock/products/{productId}/add or the by-barcode path. Provide product_id or barcode. Omit confirm for a dry-run.
Inputs: amount (required), note, price, barcode, +7 more.
grocy_stock_bookingA
Stock booking. action get is GET /api/stock/bookings/{bookingId}. undo is POST .../undo and needs confirm.
Inputs: action (required), booking_id (required), confirm.
grocy_stock_consumeB
Consume amount of a product from stock. POST consume, by product_id or barcode. Omit confirm for a dry-run.
Inputs: amount (required), barcode, confirm, spoiled, +7 more.
grocy_stock_entryCIdempotent
Stock entry. action get is GET /api/stock/entry/{entryId}. update is PUT. printlabel prints the Grocycode. Writes need confirm.
Inputs: action (required), entry_id (required), open, price, +5 more.
grocy_stock_inventoryAIdempotent
Set the stock amount of a product. POST inventory, by product_id or barcode. Omit confirm for a dry-run.
Inputs: new_amount (required), note, price, barcode, +6 more.
grocy_stock_location_entriesCRead-only
Stock entries at a location. GET /api/stock/locations/{locationId}/entries.
Inputs: location_id (required).
grocy_stock_merge_productsADestructiveIdempotent
Merge two products into one. POST /api/stock/products/{productIdToKeep}/merge/{productIdToRemove}. Omit confirm for a dry-run.
Inputs: product_id_to_keep (required), product_id_to_remove (required), confirm.
grocy_stock_openA
Mark amount of a product as opened. POST open, by product_id or barcode. Omit confirm for a dry-run.
Inputs: amount (required), barcode, confirm, product_id, +2 more.
grocy_stock_overviewBRead-only
Products currently in stock with next due date. GET /api/stock.
Inputs: no named parameters.
grocy_stock_productA
Product stock. action get, locations, entries, price_history are reads. copy and printlabel are writes and need confirm.
Inputs: action (required), product_id (required), confirm.
grocy_stock_product_by_barcodeCRead-only
Stock details of a product by barcode. GET /api/stock/products/by-barcode/{barcode}.
Inputs: barcode (required).
grocy_stock_transactionB
Stock transaction. action get lists bookings. undo reverts the transaction and needs confirm.
Inputs: action (required), transaction_id (required), confirm.
grocy_stock_transferA
Transfer amount of a product between locations. POST transfer, by product_id or barcode. Omit confirm for a dry-run.
Inputs: amount (required), location_id_to (required), location_id_from (required), barcode, +3 more.
grocy_stock_volatileCRead-only
Due soon, overdue, expired, and missing products. GET /api/stock/volatile. Optional due_soon_days.
Inputs: due_soon_days.
grocy_system_configARead-only
All Grocy config settings. GET /api/system/config. Filesystem paths are stripped from the result.
Inputs: no named parameters.
grocy_system_db_changed_timeBRead-only
Time when the Grocy database was last changed. GET /api/system/db-changed-time.
Inputs: no named parameters.
grocy_system_infoARead-only
Get Grocy version, PHP, SQLite, OS, and client. GET /api/system/info. Auth header GROCY-API-KEY.
Inputs: no named parameters.
grocy_system_localizationBRead-only
Localization strings for the authenticated user language. GET /api/system/localization-strings.
Inputs: no named parameters.
grocy_system_log_missing_localizationA
Log a missing localization string. POST /api/system/log-missing-localization. Omit confirm for a dry-run.
Inputs: text (required), confirm.
grocy_system_timeBRead-only
Current Grocy server time. GET /api/system/time. Optional offset seconds.
Inputs: offset.
grocy_task_completeAIdempotent
Mark a task completed. POST /api/tasks/{taskId}/complete. Omit confirm for a dry-run.
Inputs: task_id (required), confirm, done_time.
grocy_tasks_listCRead-only
Tasks that are not done yet. GET /api/tasks.
Inputs: no named parameters.
grocy_task_undoAIdempotent
Mark a task not completed. POST /api/tasks/{taskId}/undo. Omit confirm for a dry-run.
Inputs: task_id (required), confirm.
grocy_userfields_getCRead-only
Userfield values for one object. GET /api/userfields/{entity}/{objectId}.
Inputs: entity (required), object_id (required).
grocy_userfields_putAIdempotent
Replace userfield values for one object. PUT /api/userfields/{entity}/{objectId}. Omit confirm for a dry-run.
Inputs: entity (required), fields (required), object_id (required), confirm.
grocy_user_permissionsADestructiveIdempotent
User permissions. action get is GET /api/users/{userId}/permissions. add is POST one permissions_id. replace is PUT the full list. Writes need confirm.
Inputs: action (required), user_id (required), confirm, permissions, +1 more.
grocy_users_createA
Create a Grocy user. POST /api/users. Password is redacted in previews. Omit confirm for a dry-run.
Inputs: password (required), username (required), confirm, last_name, +2 more.
grocy_users_deleteADestructiveIdempotent
Delete a Grocy user. DELETE /api/users/{userId}. Omit confirm for a dry-run.
Inputs: user_id (required), confirm.
grocy_user_settingsBIdempotent
Current user settings. action list/get/put/delete maps to /api/user/settings. Writes need confirm.
Inputs: action (required), value, confirm, setting_key.
grocy_users_listBRead-only
List Grocy users. GET /api/users. Passwords are redacted.
Inputs: no named parameters.
grocy_users_updateBIdempotent
Edit a Grocy user. PUT /api/users/{userId}. Omit confirm for a dry-run.
Inputs: user_id (required), username (required), confirm, password, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 62 tools
Most tools target distinct domain actions, but there is meaningful overlap: grocy_stock_transaction and grocy_stock_booking both expose booking-like get/undo operations, and generic grocy_objects_list/get/create/update/delete duplicate entity-specific tools for chores, batteries, tasks, and others. The descriptions help, but an agent still has multiple plausible paths for several operations.
Tool names consistently use snake_case with a grocy_ prefix and generally follow a domain/action or domain/entity pattern. Minor inconsistency comes from multi-action aggregate tools like grocy_stock_product and grocy_stock_entry that omit the action from the name, but the overall convention is predictable.
At 62 tools, the surface is very heavy for an agent to navigate and includes several aggregate tools that could absorb more actions. While Grocy is a broad domain, the count far exceeds typical well-scoped sets and increases selection burden.
The tool set covers a wide range of Grocy domains including stock, recipes, chores, batteries, tasks, users, files, calendar, printing, and system operations. Generic object CRUD fills many gaps for entities like equipment and meal plans, though reliance on generic operations rather than dedicated tools leaves minor gaps in explicit lifecycle coverage.
Related MCP Connectors
Your household recipes, pantry, meal plan and shopping lists.
Recipes, meal plan, shopping list and pantry from the Stemma iOS app, with per-area OAuth scopes.
Read and update a Sivella household: tasks, calendar, budget, reminders, decisions and memory.
OneHaus household tools: tasks, calendar, contacts, pets, vehicles, documents and more.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAccess Home Assistant data and control devices (lights, switches, thermostats, etc).574Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage shopping lists, recipes, meal plans, and shared expenses with a KitchenOwl instance via its REST API.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage household operations including groceries, inventory, chores, recipes, and shopping lists through the Grocy self-hosted ERP system.5MIT
- FlicenseBqualityBmaintenanceEnables MCP-capable clients to interact with a self-hosted Homebox inventory instance, covering read and write operations for items, locations, labels, notifiers, maintenance, attachments, users, settings, statistics, bulk actions, QR codes, and CSV import/export.251-