Skip to main content
Glama

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:http

npm 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-mcp

Do 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

grocy_system_info

GET /api/system/info

grocy_system_db_changed_time

GET /api/system/db-changed-time

grocy_system_config

GET /api/system/config

grocy_system_time

GET /api/system/time

grocy_system_localization

GET /api/system/localization-strings

grocy_system_log_missing_localization

POST /api/system/log-missing-localization

grocy_objects_list

GET /api/objects/{entity}

grocy_objects_get

GET /api/objects/{entity}/{objectId}

grocy_objects_create

POST /api/objects/{entity}

grocy_objects_update

PUT /api/objects/{entity}/{objectId}

grocy_objects_delete

DELETE /api/objects/{entity}/{objectId}

grocy_userfields_get

GET /api/userfields/{entity}/{objectId}

grocy_userfields_put

PUT /api/userfields/{entity}/{objectId}

grocy_files_get

GET /api/files/{group}/{fileName}

grocy_files_put

PUT /api/files/{group}/{fileName}

grocy_files_delete

DELETE /api/files/{group}/{fileName}

grocy_users_list

GET /api/users

grocy_users_create

POST /api/users

grocy_users_update

PUT /api/users/{userId}

grocy_users_delete

DELETE /api/users/{userId}

grocy_user_permissions

/api/users/{userId}/permissions with action get, add, replace

grocy_current_user

GET /api/user

grocy_user_settings

/api/user/settings with action list, get, put, delete

grocy_stock_overview

GET /api/stock

grocy_stock_volatile

GET /api/stock/volatile

grocy_stock_entry

/api/stock/entry/{entryId} with action get, update, printlabel

grocy_stock_product

product stock reads plus copy and printlabel

grocy_stock_add

POST .../add by product_id or barcode

grocy_stock_consume

POST .../consume by product_id or barcode

grocy_stock_transfer

POST .../transfer by product_id or barcode

grocy_stock_inventory

POST .../inventory by product_id or barcode

grocy_stock_open

POST .../open by product_id or barcode

grocy_stock_merge_products

POST /api/stock/products/{keep}/merge/{remove}

grocy_stock_product_by_barcode

GET /api/stock/products/by-barcode/{barcode}

grocy_stock_location_entries

GET /api/stock/locations/{locationId}/entries

grocy_shopping_list

shopping list add-missing, add-overdue, add-expired, clear, add_product, remove_product

grocy_stock_booking

get or undo a stock booking

grocy_stock_transaction

get or undo a stock transaction

grocy_barcode_lookup

GET /api/stock/barcodes/external-lookup/{barcode}

grocy_recipe_fulfillment

one recipe or all recipes

grocy_recipe_consume

POST /api/recipes/{recipeId}/consume

grocy_recipe_add_missing_to_shoppinglist

add missing recipe products to a shopping list

grocy_recipe_copy

POST /api/recipes/{recipeId}/copy

grocy_recipe_printlabel

print a recipe Grocycode

grocy_chores_list

GET /api/chores

grocy_chore_get

GET /api/chores/{choreId}

grocy_chore_execute

POST /api/chores/{choreId}/execute

grocy_chore_undo_execution

undo a chore execution

grocy_chores_calculate_assignments

recalculate next assignments

grocy_chore_printlabel

print a chore Grocycode

grocy_chore_merge

merge two chores

grocy_batteries_list

GET /api/batteries

grocy_battery_get

GET /api/batteries/{batteryId}

grocy_battery_charge

track a charge cycle

grocy_battery_undo_charge

undo a charge cycle

grocy_battery_printlabel

print a battery Grocycode

grocy_tasks_list

GET /api/tasks

grocy_task_complete

complete a task

grocy_task_undo

mark a task not done

grocy_calendar_ical

GET /api/calendar/ical

grocy_calendar_sharing_link

GET /api/calendar/ical/sharing-link

grocy_print_shoppinglist

thermal print a shopping list

grocy_files_* takes the plain file_name. The connector base64-encodes it for Grocy.

Environment

Variable

Default

Role

GROCY_URL

https://example.invalid

Instance origin. No userinfo, query, or hash. A trailing /api is stripped

GROCY_API_KEY

unset

Required for an upstream call. At least 8 characters. Never printed

GROCY_ALLOW_WRITES

off

The literal true enables writes. Any other value keeps writes as a blocked preview

GROCY_CONTACT

contact@example.com

Contact inside the User-Agent. Must not contain the API key

GROCY_PER_MINUTE

30

Local sliding-window cap

GROCY_CACHE_TTL_SEC

60

TTL for successful reads. 0 disables the cache

GROCY_TIMEOUT_MS

20000

Upstream timeout

MCP_TRANSPORT

stdio

stdio or http. --http forces HTTP

PORT

3000

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 tools
grocy_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_listA
Read-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_getB
Read-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_icalA
Read-only

Household calendar as iCal text. GET /api/calendar/ical.

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_getC
Read-only

Details of one chore. GET /api/chores/{choreId}.

Inputs: chore_id (required).

grocy_chore_mergeA
DestructiveIdempotent

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_listB
Read-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_userA
Read-only

The authenticated Grocy user. GET /api/user. Passwords are redacted.

Inputs: no named parameters.

grocy_files_deleteA
DestructiveIdempotent

Delete a file. DELETE /api/files/{group}/{fileName}. Omit confirm for a dry-run.

Inputs: group (required), file_name (required), confirm.

grocy_files_getB
Read-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_putA
Idempotent

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_deleteA
DestructiveIdempotent

Delete one Grocy object. DELETE /api/objects/{entity}/{objectId}. Omit confirm for a dry-run.

Inputs: entity (required), object_id (required), confirm.

grocy_objects_getB
Read-only

Get one Grocy object. GET /api/objects/{entity}/{objectId}.

Inputs: entity (required), object_id (required).

grocy_objects_listB
Read-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_updateA
Idempotent

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_fulfillmentC
Read-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_listB
DestructiveIdempotent

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_entryC
Idempotent

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_inventoryA
Idempotent

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_entriesC
Read-only

Stock entries at a location. GET /api/stock/locations/{locationId}/entries.

Inputs: location_id (required).

grocy_stock_merge_productsA
DestructiveIdempotent

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_overviewB
Read-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_barcodeC
Read-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_volatileC
Read-only

Due soon, overdue, expired, and missing products. GET /api/stock/volatile. Optional due_soon_days.

Inputs: due_soon_days.

grocy_system_configA
Read-only

All Grocy config settings. GET /api/system/config. Filesystem paths are stripped from the result.

Inputs: no named parameters.

grocy_system_db_changed_timeB
Read-only

Time when the Grocy database was last changed. GET /api/system/db-changed-time.

Inputs: no named parameters.

grocy_system_infoA
Read-only

Get Grocy version, PHP, SQLite, OS, and client. GET /api/system/info. Auth header GROCY-API-KEY.

Inputs: no named parameters.

grocy_system_localizationB
Read-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_timeB
Read-only

Current Grocy server time. GET /api/system/time. Optional offset seconds.

Inputs: offset.

grocy_task_completeA
Idempotent

Mark a task completed. POST /api/tasks/{taskId}/complete. Omit confirm for a dry-run.

Inputs: task_id (required), confirm, done_time.

grocy_tasks_listC
Read-only

Tasks that are not done yet. GET /api/tasks.

Inputs: no named parameters.

grocy_task_undoA
Idempotent

Mark a task not completed. POST /api/tasks/{taskId}/undo. Omit confirm for a dry-run.

Inputs: task_id (required), confirm.

grocy_userfields_getC
Read-only

Userfield values for one object. GET /api/userfields/{entity}/{objectId}.

Inputs: entity (required), object_id (required).

grocy_userfields_putA
Idempotent

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_permissionsA
DestructiveIdempotent

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_deleteA
DestructiveIdempotent

Delete a Grocy user. DELETE /api/users/{userId}. Omit confirm for a dry-run.

Inputs: user_id (required), confirm.

grocy_user_settingsB
Idempotent

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_listB
Read-only

List Grocy users. GET /api/users. Passwords are redacted.

Inputs: no named parameters.

grocy_users_updateB
Idempotent

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

    B3/5.0

    Scored across 62 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage shopping lists, recipes, meal plans, and shared expenses with a KitchenOwl instance via its REST API.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage household operations including groceries, inventory, chores, recipes, and shopping lists through the Grocy self-hosted ERP system.
      5
      MIT
    • F
      license
      B
      quality
      B
      maintenance
      Enables 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.
      25
      1
      -