grocy-mcp

Python MCP server and CLI for Grocy.

grocy-mcp lets AI agents and terminal users work with Grocy through one shared codebase. It exposes stock, shopping lists, recipes, chores, batteries, equipment, calendar exports, file groups, print helpers, workflow preview/apply helpers, discovery tools, and generic entity management through:

• an MCP server for tools like Claude Desktop, Claude Code, and other MCP clients
• a grocy CLI for direct command-line use

Choose your path

• Want to connect Grocy to Claude, ChatGPT, or another MCP client? Install grocy-mcp, run the MCP server, and point your client at it.
• Want to manage Grocy from the terminal? Install the package and use the grocy CLI directly.
• Want to build chat, OCR, or photo-driven flows? Normalize items outside this repo, then call the workflow preview/apply tools here.

If you only want the fastest possible first run, this is enough:

pip install grocy-mcp
export GROCY_URL="https://grocy.example.com"
export GROCY_API_KEY="your-api-key-here"
grocy stock overview

Why this project

Grocy already has a solid REST API, but most day-to-day interactions still require either:

• clicking through the Grocy UI
• writing one-off API scripts
• wiring ad hoc automations around numeric IDs

grocy-mcp packages those API capabilities into a cleaner operator experience:

• human-friendly names instead of IDs for common flows
• a reusable MCP surface for AI agents
• a mirrored CLI for shell workflows and scripting
• one shared implementation for both interfaces

Features

• 80+ MCP tools across stock, shopping, recipes, chores, locations, tasks, meal plans, batteries, equipment, calendar, files, print, discovery, workflow helpers, and system operations
• Full Typer CLI with grouped subcommands under grocy
• Global --json mode for machine-readable output on the supported list/view/reporting commands
• Top-level CLI config overrides via --url and --api-key
• Name-based resolution for products, recipes, chores, locations, batteries, and equipment
• Stable workflow-oriented JSON contracts for preview/apply flows driven by chat, OCR, or vision clients
• Batch preview/apply helpers for product matching, stock intake, and shopping-list reconciliation
• First-class catalog helpers for shopping metadata, quantity metadata, task categories, meal-plan sections, and price-history views