Private Grocy MCP (pv-grocy)

An MCP server for a household's Grocy: stock, shopping lists, recipes, meal plan, chores, tasks, batteries and equipment. Ask an assistant what is expiring, what you can cook tonight, or what to buy; with writes switched on, have it book a receipt into stock, tick off the shopping list or plan the week's meals.

• Read-only by default. Writes need a deployment switch and a token with write or full access; irreversible operations are full only (ADR-0002).

• No silent data errors. A write is never sent twice, and never lands on a record you did not name exactly (ADR-0003). Every stock change returns a transaction_id that stock_undo reverts.

• Typed tools. 76 tools with JSON Schema arguments, structured results and paging.

• Hardened container. Non-root, read-only root filesystem, no local state.

Tested with Grocy 4.7.1; needs Grocy 4.4.1 or later. Not affiliated with the Grocy project.

What it does

Names. Tools take an id or an exact name ("Milk", "milk", " MILK " all work). A name that matches nothing or several things fails with up to five candidates; use search or stock_search to find the right one. Nothing is ever resolved by partial match.

Batch changes come in two halves: a preview that matches and proposes (and never guesses), then an apply that takes only ids. For example, for a receipt: workflow_stock_intake_preview → confirm with the user → workflow_stock_intake_apply with the preview's apply_items.

Related MCP server: grocy-mcp

Security model

• Plain HTTP with bearer tokens: run it on a private network next to Grocy, and put a TLS proxy or tunnel with its own authentication in front of it for anything remote. Never publish the port to the internet.

• Tokens are stored as SHA-256 hashes; one token per client, each with its own access level and write limit, so each can be revoked alone.

• Give pv-grocy its own Grocy API key (Grocy → Manage API keys), so it can be revoked independently. The key has full access to Grocy; pv-grocy is what limits it.

• Grocy data is untrusted: results are marked content_trust: "untrusted", and the model is told never to follow instructions found in them.

Details: SECURITY.md.

Quick start (Docker Compose)

cp compose.example.yml compose.yml
cp config/pv-grocy.example.yaml config/pv-grocy.yaml
docker run --rm ghcr.io/happycynic/pv-grocy:latest hash-token   # put the sha256 in pv-grocy.yaml
echo "PV_GROCY_API_KEY=<a dedicated Grocy API key>" > pv-grocy.env && chmod 600 pv-grocy.env
docker compose up -d
curl -s http://127.0.0.1:8772/healthz?deep=1    # {"status":"ok","grocy_version":"4.7.1"}

Point MCP clients at http://<host>:8772/mcp with Authorization: Bearer <token>.

Configuration

config/pv-grocy.yaml (see the example): Grocy's URL and the tokens with their access levels. Environment:

Each tool call writes one JSON audit line to stdout (tool, token label, outcome, latency; free-text arguments by size only).

Development

uv python install 3.14 && uv sync --frozen --all-groups
uv run pytest && uv run ruff check . && uv run ruff format --check . && uv run mypy

The tests use an in-process fake of the Grocy API; pytest -m live runs against a real one. See CONTRIBUTING.md and docs/design.md.

License

Apache License 2.0. Copyright 2026 Happy Cynic Software LLC.