Hermes Grocy MCP

io.github.rusty4444Published by GitHub account rusty4444v0.2.1Updated Oct 24, 2026

MCP server for Grocy household ERP inventory and shopping workflows.

VerifiedSTDIODesktop onlyProductivity & WorkflowBusiness & Commerce

Overview

AI-generated overview

A local MCP server that connects an assistant to a self-hosted Grocy household ERP for products, stock, shopping lists, chores and tasks.

What you can do
Inspect Grocy system and version status, and list, search or fetch products, including lookup by barcode or Grocycode. Read current stock, volatile stock, per-product stock details and individual stock entries. List shopping lists and their items, and add or remove products and amounts. Add, consume or set inventory amounts for product stock. List, create and update generic Grocy entities and set userfields from JSON. List chores with next-due times, execute chores, and list tasks.
When to use it
Useful when you run a self-hosted Grocy instance and want an assistant to answer questions about stock, shopping lists, chores and tasks, or to make routine household inventory changes without hand-crafting REST calls.
Requirements
Runs locally as a Python package (installed via pipx or uvx). Needs a Grocy base URL in GROCY_BASE_URL (defaults to the public demo instance) and, for private instances or write access, an API key in GROCY_API_KEY. Optional GROCY_TIMEOUT sets the HTTP timeout. Network access to the Grocy instance is required.
Before you install
Many tools write directly to Grocy data: stock additions and consumption, inventory changes, shopping list edits, generic entity create/update, userfield changes and chore execution. Point it at a private instance rather than a shared public demo for anything that mutates data. Keep GROCY_API_KEY in the client environment config or a secret manager, not in source control.

Installation

In SourceWeft

  1. Open Hermes Grocy MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

bash
pipx install git+https://github.com/rusty4444/grocy-mcp.git

Or from a checkout:

bash
python -m venv .venvsource .venv/bin/activatepip 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

json
{  "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

bash
python -m venv .venvsource .venv/bin/activatepip install -e '.[dev]'ruff check .pytestpython 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.

Source: README.md at commit 1961e6e

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts