English Français العربية

Hermes Grocy MCP

Official registry E-commerce

MCP server for Grocy household ERP inventory and shopping workflows.

Source code Website Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package hermes-grocy-mcp
Claude Code 
claude mcp add hermes-grocy-mcp -e 'GROCY_BASE_URL=<GROCY_BASE_URL>' -e 'GROCY_API_KEY=<your grocy_api_key>' -- uvx hermes-grocy-mcp==0.2.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "hermes-grocy-mcp": {
            "command": "uvx",
            "args": [
                "hermes-grocy-mcp==0.2.1"
            ],
            "env": {
                "GROCY_BASE_URL": "<GROCY_BASE_URL>",
                "GROCY_API_KEY": "<your grocy_api_key>"
            }
        }
    }
}

Environment variables

  • GROCY_BASE_URL Grocy base URL, with or without /api
  • GROCY_API_KEY secret Grocy API key for private instances or write access

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Grocy MCP
  2. Why this exists
  3. Installation
  4. Configuration
  5. MCP client config
  6. Tools
  7. Development and validation
  8. Safety

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:

VariableRequiredDefaultDescription
GROCY_BASE_URLNohttps://demo.grocy.infoGrocy base URL, with or without /api
GROCY_API_KEYNo for public/demo read-only instances, yes for private/write accessunsetGrocy API key sent as GROCY-API-KEY
GROCY_TIMEOUTNo20HTTP 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

ToolPurpose
grocy_system_infoGrocy version and runtime details
grocy_list_productsList configured products
grocy_search_productsSearch products by name/description
grocy_get_productFetch one product object
grocy_lookup_product_by_barcodeResolve a barcode/Grocycode
grocy_stock_overviewCurrent stock rows
grocy_volatile_stockDue, overdue, expired, or missing products
grocy_product_stock_detailsDetailed stock state for one product
grocy_product_stock_entriesIndividual stock entries in next-use order
grocy_common_entitiesCommon generic entity names useful with CRUD tools
grocy_list_shopping_listsConfigured shopping lists
grocy_list_shopping_list_itemsCurrent shopping list rows, optionally filtered by list id
grocy_list_entityList any generic Grocy entity
grocy_get_entity_objectFetch any generic entity object
grocy_create_entity_objectPOST a generic entity object from JSON
grocy_update_entity_objectPUT a generic entity object from JSON
grocy_add_stockAdd product amount to stock
grocy_consume_stockConsume/remove product amount from stock
grocy_inventory_productSet product inventory amount
grocy_add_product_to_shopping_listAdd a product to a shopping list
grocy_remove_product_from_shopping_listRemove a product from a shopping list
grocy_set_userfieldsSet userfield values on an entity object
grocy_list_choresList chores including computed next-due times
grocy_execute_choreExecute (mark done) a chore, optionally backdated
grocy_list_tasksList tasks

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.

Frequently asked questions

What is Hermes Grocy MCP?

MCP server for Grocy household ERP inventory and shopping workflows.

How do I install Hermes Grocy MCP?

It runs on your machine. In Claude Code: claude mcp add hermes-grocy-mcp -e 'GROCY_BASE_URL=<GROCY_BASE_URL>' -e 'GROCY_API_KEY=<your grocy_api_key>' -- uvx hermes-grocy-mcp==0.2.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Hermes Grocy MCP need an API key?

Yes. It expects GROCY_API_KEY, which you set in its configuration.

Is Hermes Grocy MCP open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Hermes Grocy MCP?

It is published by rusty4444. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.