Skip to main content
Glama
Grocy MCP Server

Grocy MCP Server

by rabefabi

Grocy MCP Server

An MCP (Model Context Protocol) server that lets AI agents manage a Grocy instance through natural language: pantry stock, expiry dates, shopping lists, recipes and meal plans. Ships as a Home Assistant add-on and also runs standalone.

Status: experimental (0.x). Expect breaking changes.

Features

  • Inventory — view stock by location, find expiring items, log purchases, consumption, opening and transfers

  • Shopping list — view, add, remove, add a recipe's missing ingredients

  • Recipes — search, check fulfillment against stock, create and edit, add ingredients, upload images, consume a cooked recipe

  • Meal plan — view, add and remove entries

  • Product database — create and update products, quantity-unit conversions, Open Food Facts lookup

Tools accept human-readable names and resolve them to Grocy IDs. Ambiguous matches are surfaced instead of guessed.

Related MCP server: grocy-mcp

Installation

Home Assistant add-on

  1. In Home Assistant go to Settings → Add-ons → Add-on Store → ⋮ → Repositories and add:

    https://github.com/rabefabi/grocy-mcp
  2. Install Grocy MCP Server, set grocy_url and grocy_api_token, start it.

Option

Required

Description

grocy_url

yes

Base URL of your Grocy instance, e.g. http://a0d7b954-grocy (DOCS.md)

grocy_api_token

yes

API key from Grocy (Settings → Manage API keys)

log_level

no

debug, info, warning, error (default info)

The add-on publishes no port by default, because the MCP endpoint has no authentication. DOCS.md describes how to connect a client: by enabling port 8001 or through nginx with TLS and a token.

Docker (standalone)

cp .env.example .env   # set GROCY_URL, GROCY_API_TOKEN and MCP_BEARER_TOKEN
docker compose -f docker-compose.grocy-mcp-standalone.yml --env-file .env up -d --build

The MCP server has no authentication of its own, so the compose file puts Caddy in front of it (Caddyfile.standalone). Only Caddy's HTTPS port is published; the MCP server's port stays inside the Docker network. Caddy

  • terminates TLS. By default the certificate comes from Caddy's own CA, so a client either trusts that CA (docker compose -f docker-compose.grocy-mcp-standalone.yml cp caddy:/data/caddy/pki/authorities/local/root.crt .) or skips certificate verification. With MCP_TLS set to an email address and MCP_SITE_ADDRESS to a public domain that points at the host, Caddy gets a public certificate instead; this needs MCP_HTTPS_PORT=443.

  • rejects requests without Authorization: Bearer <MCP_BEARER_TOKEN> with 401. The token has no default; generate one with openssl rand -hex 32.

  • rejects clients outside private networks with 403. MCP_ALLOWED_IPS takes other ranges, in Caddy's remote_ip syntax.

The endpoint is https://<MCP_SITE_ADDRESS>:<MCP_HTTPS_PORT>/mcp, by default https://localhost:8443/mcp.

Local (development)

cp .env.example .env
uv sync
just grocy-mcp-run staging     # runs against the Grocy in .env

Variable

Required

Description

GROCY_URL

yes

Base URL of your Grocy instance (no trailing slash)

GROCY_API_TOKEN

yes

API key from Grocy

LOG_LEVEL

no

debug, info, warning, error (default info)

MCP_PORT

no

Port the server listens on (default 8000)

Connecting an MCP client

The server speaks Streamable HTTP at http://<host>:<port>/mcp. A health endpoint is at /health.

Example client config for the standalone Docker setup:

{
  "mcpServers": {
    "grocy": {
      "type": "http",
      "url": "https://<host>:8443/mcp",
      "headers": { "Authorization": "Bearer <MCP_BEARER_TOKEN>" }
    }
  }
}

The server itself has no client authentication: put it behind a proxy that checks a token (Caddy in the standalone setup, nginx for the add-on, see DOCS.md) or only expose it inside a trusted network.

Skills

skills/ contains skill documents (SKILL.md) that teach an AI agent the right tool sequences for each workflow: inventory, shopping list, recipe discovery, recipe import, meal planning, product management and a household profile. Load them into your MCP client alongside the server.

Development

Requires Docker, just and uv with Python 3.13+. Run just to list all recipes.

just grocy-up      # start a local Grocy test instance (http://localhost:9283, admin/admin)
just grocy-token   # write an API key to .env.grocy.test
just grocy-seed    # load representative test data
just grocy-test    # run the test suite (extra args are passed to pytest)
just grocy-down    # remove the test instance
just typecheck     # type-check src/ with pyright

See CLAUDE.md for project structure and conventions, and docs/adr/ for architecture decisions.

License

Apache License 2.0 — see LICENSE and NOTICE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables interaction with Grocy's API through MCP, allowing management of grocery inventory, shopping lists, and household tasks via natural language.
      203 npm
      28
      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
    • A
      license
      C
      quality
      C
      maintenance
      Enables AI agents and terminal users to manage Grocy household inventory, shopping lists, recipes, chores, and related household operations through MCP tools and a command-line interface.
      89
      MIT