grocy-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PORT | No | HTTP listen port when using HTTP transport. | 3000 |
| GROCY_URL | Yes | Grocy instance origin. No userinfo, query, or hash. A trailing /api is stripped. | https://example.invalid |
| GROCY_API_KEY | Yes | Grocy API key. Required for upstream calls. At least 8 characters. Never printed. | |
| GROCY_CONTACT | No | Contact value included in the User-Agent. Must not contain the API key. | |
| MCP_TRANSPORT | No | Transport mode: stdio or http. --http forces HTTP mode. | stdio |
| GROCY_RATE_LIMIT | No | Local sliding-window rate-limit cap, expressed per minute. | |
| GROCY_TIMEOUT_MS | No | Upstream request timeout in milliseconds. | 20000 |
| GROCY_ALLOW_WRITES | No | Set to the literal true to allow writes. Any other value keeps writes blocked as dry-run previews. | false |
| GROCY_CACHE_TTL_SEC | No | TTL in seconds for successful read caching. Set to 0 to disable the cache. | 60 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| grocy_system_infoA | Get Grocy version, PHP, SQLite, OS, and client. GET /api/system/info. Auth header GROCY-API-KEY. |
| grocy_system_db_changed_timeB | Time when the Grocy database was last changed. GET /api/system/db-changed-time. |
| grocy_system_configA | All Grocy config settings. GET /api/system/config. Filesystem paths are stripped from the result. |
| grocy_system_timeB | Current Grocy server time. GET /api/system/time. Optional offset seconds. |
| grocy_system_localizationB | Localization strings for the authenticated user language. GET /api/system/localization-strings. |
| grocy_system_log_missing_localizationA | Log a missing localization string. POST /api/system/log-missing-localization. Omit confirm for a dry-run. |
| grocy_objects_listB | 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. |
| grocy_objects_getB | Get one Grocy object. GET /api/objects/{entity}/{objectId}. |
| grocy_objects_createA | Create one Grocy object. POST /api/objects/{entity}. fields is the entity JSON. Omit confirm for a dry-run. |
| grocy_objects_updateA | Edit one Grocy object. PUT /api/objects/{entity}/{objectId}. Omit confirm for a dry-run. |
| grocy_objects_deleteA | Delete one Grocy object. DELETE /api/objects/{entity}/{objectId}. Omit confirm for a dry-run. |
| grocy_userfields_getC | Userfield values for one object. GET /api/userfields/{entity}/{objectId}. |
| grocy_userfields_putA | Replace userfield values for one object. PUT /api/userfields/{entity}/{objectId}. Omit confirm for a dry-run. |
| grocy_files_getB | 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. |
| grocy_files_putA | Upload a file as application/octet-stream. PUT /api/files/{group}/{fileName}. content_base64 is the file bytes. Omit confirm for a dry-run. |
| grocy_files_deleteA | Delete a file. DELETE /api/files/{group}/{fileName}. Omit confirm for a dry-run. |
| grocy_users_listB | List Grocy users. GET /api/users. Passwords are redacted. |
| grocy_users_createA | Create a Grocy user. POST /api/users. Password is redacted in previews. Omit confirm for a dry-run. |
| grocy_users_updateB | Edit a Grocy user. PUT /api/users/{userId}. Omit confirm for a dry-run. |
| grocy_users_deleteA | Delete a Grocy user. DELETE /api/users/{userId}. Omit confirm for a dry-run. |
| grocy_user_permissionsA | 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. |
| grocy_current_userA | The authenticated Grocy user. GET /api/user. Passwords are redacted. |
| grocy_user_settingsB | Current user settings. action list/get/put/delete maps to /api/user/settings. Writes need confirm. |
| grocy_stock_overviewB | Products currently in stock with next due date. GET /api/stock. |
| grocy_stock_volatileC | Due soon, overdue, expired, and missing products. GET /api/stock/volatile. Optional due_soon_days. |
| grocy_stock_entryC | Stock entry. action get is GET /api/stock/entry/{entryId}. update is PUT. printlabel prints the Grocycode. Writes need confirm. |
| grocy_stock_productA | Product stock. action get, locations, entries, price_history are reads. copy and printlabel are writes and need confirm. |
| 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. |
| grocy_stock_consumeB | Consume amount of a product from stock. POST consume, by product_id or barcode. Omit confirm for a dry-run. |
| grocy_stock_transferA | Transfer amount of a product between locations. POST transfer, by product_id or barcode. Omit confirm for a dry-run. |
| grocy_stock_inventoryA | Set the stock amount of a product. POST inventory, by product_id or barcode. Omit confirm for a dry-run. |
| grocy_stock_openA | Mark amount of a product as opened. POST open, by product_id or barcode. Omit confirm for a dry-run. |
| grocy_stock_merge_productsA | Merge two products into one. POST /api/stock/products/{productIdToKeep}/merge/{productIdToRemove}. Omit confirm for a dry-run. |
| grocy_stock_product_by_barcodeC | Stock details of a product by barcode. GET /api/stock/products/by-barcode/{barcode}. |
| grocy_stock_location_entriesC | Stock entries at a location. GET /api/stock/locations/{locationId}/entries. |
| grocy_shopping_listB | Shopping list helpers. action add_missing, add_overdue, add_expired, clear, add_product, remove_product. All writes. Omit confirm for a dry-run. |
| grocy_stock_bookingA | Stock booking. action get is GET /api/stock/bookings/{bookingId}. undo is POST .../undo and needs confirm. |
| grocy_stock_transactionB | Stock transaction. action get lists bookings. undo reverts the transaction and needs confirm. |
| grocy_barcode_lookupA | External barcode lookup. GET /api/stock/barcodes/external-lookup/{barcode}. add=true also creates the product and needs confirm. |
| grocy_recipe_fulfillmentC | Recipe stock fulfillment. action one is GET /api/recipes/{recipeId}/fulfillment. all is GET /api/recipes/fulfillment. |
| grocy_recipe_consumeA | Consume in-stock ingredients of a recipe. POST /api/recipes/{recipeId}/consume. Omit confirm for a dry-run. |
| 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. |
| grocy_recipe_copyA | Copy a recipe. POST /api/recipes/{recipeId}/copy. Omit confirm for a dry-run. |
| grocy_recipe_printlabelB | Print the Grocycode label for a recipe. GET /api/recipes/{recipeId}/printlabel. Omit confirm for a dry-run. |
| grocy_chores_listB | All chores with next estimated execution. GET /api/chores. |
| grocy_chore_getC | Details of one chore. GET /api/chores/{choreId}. |
| grocy_chore_executeA | Track a chore execution. POST /api/chores/{choreId}/execute. Omit confirm for a dry-run. |
| grocy_chore_undo_executionA | Undo a chore execution. POST /api/chores/executions/{executionId}/undo. Omit confirm for a dry-run. |
| grocy_chores_calculate_assignmentsB | Recalculate next chore user assignments. POST /api/chores/executions/calculate-next-assignments. Omit confirm for a dry-run. |
| grocy_chore_printlabelA | Print the Grocycode label for a chore. GET /api/chores/{choreId}/printlabel. Omit confirm for a dry-run. |
| grocy_chore_mergeA | Merge two chores. POST /api/chores/{choreIdToKeep}/merge/{choreIdToRemove}. Omit confirm for a dry-run. |
| grocy_batteries_listA | All batteries with next estimated charge time. GET /api/batteries. |
| grocy_battery_getB | Details of one battery. GET /api/batteries/{batteryId}. |
| grocy_battery_chargeA | Track a battery charge cycle. POST /api/batteries/{batteryId}/charge. Omit confirm for a dry-run. |
| grocy_battery_undo_chargeA | Undo a battery charge cycle. POST /api/batteries/charge-cycles/{chargeCycleId}/undo. Omit confirm for a dry-run. |
| grocy_battery_printlabelA | Print the Grocycode label for a battery. GET /api/batteries/{batteryId}/printlabel. Omit confirm for a dry-run. |
| grocy_tasks_listC | Tasks that are not done yet. GET /api/tasks. |
| grocy_task_completeA | Mark a task completed. POST /api/tasks/{taskId}/complete. Omit confirm for a dry-run. |
| grocy_task_undoA | Mark a task not completed. POST /api/tasks/{taskId}/undo. Omit confirm for a dry-run. |
| grocy_calendar_icalA | Household calendar as iCal text. GET /api/calendar/ical. |
| grocy_calendar_sharing_linkB | Public sharing link for the iCal calendar. GET /api/calendar/ical/sharing-link. |
| grocy_print_shoppinglistB | Print a shopping list on the configured thermal printer. GET /api/print/shoppinglist/thermal. Omit confirm for a dry-run. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.