Grocy MCP
A Model Context Protocol (MCP) server for Grocy, the self-hosted household ERP for groceries, inventory, chores, batteries, recipes, tasks, and shopping lists.
This server focuses on AI-friendly household operations that are awkward through generic REST clients:
- Inspect Grocy system/version status
- List, search, and inspect products
- Read current stock, volatile stock, product stock details, and individual stock entries
- List current shopping list items and add/remove products from shopping lists
- Look up products by barcode/Grocycode
- List and inspect any
/api/objects/{entity}entity - Create/update generic entity objects from JSON
- Add, consume, and inventory product stock
- Add/remove product amounts from shopping lists
Why this exists
Grocy has a strong REST API, but MCP coverage is sparse and usually either incomplete or tightly coupled to one client's workflow. This package gives Hermes, Claude Desktop, Cursor, and other MCP clients a small, explicit, documented tool surface.
Installation
pipx install git+https://github.com/rusty4444/grocy-mcp.git
Or from a checkout:
python -m venv .venv
source .venv/bin/activate
pip install -e .
Configuration
The server reads configuration from environment variables:
| Variable | Required | Default | Description |
|---|---|---|---|
GROCY_BASE_URL |
No | https://demo.grocy.info |
Grocy base URL, with or without /api |
GROCY_API_KEY |
No for public/demo read-only instances, yes for private/write access | unset | Grocy API key sent as GROCY-API-KEY |
GROCY_TIMEOUT |
No | 20 |
HTTP timeout in seconds |
Grocy API keys are managed in Grocy under Manage API keys. The API accepts the GROCY-API-KEY header.
MCP client config
{
"mcpServers": {
"grocy": {
"command": "grocy-mcp",
"env": {
"GROCY_BASE_URL": "https://grocy.example.com",
"GROCY_API_KEY": "your-api-key"
}
}
}
}
Tools
| Tool | Purpose |
|---|---|
grocy_system_info |
Grocy version and runtime details |
grocy_list_products |
List configured products |
grocy_search_products |
Search products by name/description |
grocy_get_product |
Fetch one product object |
grocy_lookup_product_by_barcode |
Resolve a barcode/Grocycode |
grocy_stock_overview |
Current stock rows |
grocy_volatile_stock |
Due, overdue, expired, or missing products |
grocy_product_stock_details |
Detailed stock state for one product |
grocy_product_stock_entries |
Individual stock entries in next-use order |
grocy_common_entities |
Common generic entity names useful with CRUD tools |
grocy_list_shopping_lists |
Configured shopping lists |
grocy_list_shopping_list_items |
Current shopping list rows, optionally filtered by list id |
grocy_list_entity |
List any generic Grocy entity |
grocy_get_entity_object |
Fetch any generic entity object |
grocy_create_entity_object |
POST a generic entity object from JSON |
grocy_update_entity_object |
PUT a generic entity object from JSON |
grocy_add_stock |
Add product amount to stock |
grocy_consume_stock |
Consume/remove product amount from stock |
grocy_inventory_product |
Set product inventory amount |
grocy_add_product_to_shopping_list |
Add a product to a shopping list |
grocy_remove_product_from_shopping_list |
Remove a product from a shopping list |
Development and validation
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
ruff check .
pytest
python scripts/live_readonly_test.py
The live read-only test defaults to https://demo.grocy.info, avoiding mutations on shared infrastructure. It has been validated against Grocy API 4.6.0. Use a private Grocy instance plus GROCY_API_KEY for write-path testing.
Safety
Write-capable tools directly mutate Grocy data. Prefer read-only tools when using public demos. Keep GROCY_API_KEY in MCP client environment config or a secret manager, never in source control.
Metadata
Release files for hermes-grocy-mcp 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hermes_grocy_mcp-0.2.1.tar.gz | 13.1 kB | Without provenance | Details for hermes_grocy_mcp-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hermes_grocy_mcp-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for hermes_grocy_mcp-0.2.1-py3-none-any.whl |
Total release size: 22.6 kB
Release files / hermes_grocy_mcp-0.2.1.tar.gz
| Download URL | hermes_grocy_mcp-0.2.1.tar.gz |
|---|---|
| Size | 13.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0903e6ec7627ba0c89cfd76fcf15ab518b3746962ed368fd8594750c4d098c69
|
|
BLAKE2b-256 checksum How to use checksums |
f1ab8052f0feae4935528b42d8e693280f457f5082e6f76cf49591bd765a8f81
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / hermes_grocy_mcp-0.2.1-py3-none-any.whl
| Download URL | hermes_grocy_mcp-0.2.1-py3-none-any.whl |
|---|---|
| Size | 9.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1697f3d012c4e6edfe34e36ba470bc51e030b4e7fdea68162323274dc8379b55
|
|
BLAKE2b-256 checksum How to use checksums |
63ae832943655e2e1ed1dc1c478ab1aa2ae6bc3158c777f6da749aef0beb5e53
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for hermes-grocy-mcp 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.