Grocy
Model Context Protocol (MCP) server for Grocy integration
Ask AI about Grocy
Powered by Claude Β· Grounded in docs
I know everything about Grocy. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP Grocy
π΄ Opinionated Fork Notice
This is a heavily opinionated fork of saya6k/mcp-grocy-api that has diverged significantly to warrant a separate identity. This MCP prioritizes usability over features.
Why This Fork Exists:
- The original wrapper exposes the entire Grocy API unprocessed, leading to context overload and LLM confusion
- Grocy's API design choices and limitations cause error-prone interactions
- Generic API exposure increases hallucination and near-miss results
This Fork's Philosophy:
- Filters and augments data with relevant context for better LLM comprehension
- Reduces API calls by combining common operations to minimize error chains
- Optimizes for reliability and repeatability over feature completeness
- Opinionated workflows that may not match everyone's preferences
If you need complete API access, use the original fork. This version trades flexibility for focused, dependable grocery management workflows.
π― What This MCP Does
Transform your LLM into an intelligent household management assistant with focused tools for:
π¦ Stock Management
- Track inventory across multiple locations with precision
- Record purchases and consumption with automatic stock updates
- Monitor expiry dates and get volatile stock alerts
- Transfer products between storage locations
π Smart Shopping & Planning
- Maintain shopping lists with intelligent quantity management
- Plan meals with recipe scheduling and fulfillment checking
- Automatically add missing ingredients to shopping lists
- Track shopping locations and optimize store visits
π½οΈ Recipe & Meal Workflows
- Find recipes with fuzzy search capabilities
- Check if recipes can be made with current stock
- Complete cooking workflows with portion control
- Integrate meal planning with inventory consumption
π Household Management
- Manage chores, tasks, and battery tracking
- Get product price history for budgeting
- Organize products by groups and categories
- Print labels for stock entries
β‘ Quick Start
-
Get your Grocy API key from your Grocy instance (User Settings β API Keys)
-
Set up with Docker Compose:
# Get the project git clone https://github.com/miguelangel-nubla/mcp-grocy.git cd mcp-grocy # Configure cp .env.example .env # Edit .env with your GROCY_BASE_URL and GROCY_API_KEY # Run docker compose up -d
Try Without Grocy
Test with mock data (no real Grocy instance needed):
# In .env file, any values work for mock mode
GROCY_BASE_URL=http://mock
GROCY_API_KEY=mock
npm install && npm run dev
Requirements (Node.js & tooling)
- Node.js: 22 or newer as declared in
package.jsonengines. GitHub Actions and.nvmrcuse Node 22 for CI and local alignment. - Docker: the default image is
node:22-alpineso the container matches that major version (Home Assistant addon builds still override the base image). - TypeScript: 5.9 in this repo; TypeScript 6 is waiting on
typescript-eslintto declare compatible peer support. npm audit: any remaining findings are often inside nested tooling (e.g. bundlednpm), not application dependencies. Usenpm audit/npm audit fixon a branch when refreshing the lockfile.- Quality checks:
npm run lint(ESLint),npm run format:check(Prettier),npm test(Vitest).
Installation
NPM
git clone -b main https://github.com/miguelangel-nubla/mcp-grocy.git
cd mcp-grocy
npm install
npm run build
Docker
docker run -e GROCY_API_KEY=your_api_key -e GROCY_BASE_URL=http://your-grocy-instance ghcr.io/miguelangel-nubla/mcp-grocy:latest
Docker Compose (Recommended)
Create a docker-compose.yml:
services:
mcp-grocy:
image: ghcr.io/miguelangel-nubla/mcp-grocy:latest
env_file:
- .env
restart: unless-stopped
Then:
cp .env.example .env
# Edit .env with your configuration
docker compose up -d
βοΈ Configuration
Quick Setup
-
Get your Grocy API key:
- Open your Grocy instance β User Settings β API Keys
- Create a new API key and copy it
-
Configure the server:
cp .env.example .env # Edit .env with your GROCY_BASE_URL and GROCY_API_KEY -
Essential variables:
GROCY_BASE_URL- Your Grocy instance URLGROCY_API_KEY- Your Grocy API key
Configuration Options
| Method | Use Case | Command |
|---|---|---|
.env file | Recommended for most users | cp .env.example .env |
| Environment variables | CI/CD, containers | GROCY_BASE_URL=... GROCY_API_KEY=... mcp-grocy |
| Tool configuration | Customize functionality | Edit tools section in mcp-grocy.yaml |
π For complete configuration reference: See Configuration Guide
π Usage Modes
Production Mode
Start with your real Grocy instance:
npm start
Development/Testing Mode
Use mock data (no Grocy instance required):
npm run dev
HTTP Server Mode
Enable web-based access via HTTP/SSE:
# In .env: ENABLE_HTTP_SERVER=true
npm start
# Access via http://localhost:8080/mcp
π Documentation & Resources
| Resource | Purpose | When to Use |
|---|---|---|
| π API Reference | Complete tool documentation | Tool usage and examples |
| βοΈ Configuration Guide | Advanced configuration reference | Detailed setup, presets, troubleshooting |
| π .env.example | Environment configuration template | Copy and customize for your setup |
| π§ͺ MCP Inspector | Protocol debugging | Debug MCP interactions |
Bundled MCP resources (from resources/list): mcp-grocy://examples, mcp-grocy://response-format, mcp-grocy://config β markdown docs shipped with the server. The URI scheme matches package.json name (previously some builds used grocy-api://β¦; update pinned URIs in clients or prompts if you relied on that).
π Troubleshooting
Common Issues
"Connection refused" or "Cannot connect to Grocy"
- Verify
GROCY_BASE_URLis correct and accessible - Check that your Grocy instance is running
- For HTTPS URLs, ensure SSL certificate is valid or disable verification with
GROCY_ENABLE_SSL_VERIFY=false
"Invalid API key" or "Authentication failed"
- Verify your
GROCY_API_KEYis correct - Check that the API key exists in your Grocy instance (User Settings β API Keys)
- Ensure the API key has proper permissions
"Tool not found" errors
- Check if the tool is enabled in your
mcp-grocy.yamlfile - Verify you're using the correct tool names from the API reference
Large response errors
- Increase
REST_RESPONSE_SIZE_LIMITif you have many products/stock entries - Consider disabling unused tools in
mcp-grocy.yaml
Debug Mode
Enable detailed logging and use the MCP inspector:
# Launch MCP inspector for protocol debugging
npm run inspector
# Run with mock data for testing
npm run dev
π οΈ Development
Prerequisites
- Node.js 22 or newer (see Requirements above)
- Grocy instance (optional: use placeholder URLs/keys in
.envfor local runs)
Development Setup
# Clone and install
git clone https://github.com/miguelangel-nubla/mcp-grocy.git
cd mcp-grocy
npm install
# Configure for development
cp .env.example .env
# Edit .env with your settings (or use mock values)
# Build and run
npm run build
npm start
Development Commands
| Command | Description |
|---|---|
npm run build | Build TypeScript to JavaScript |
npm start | Run the built server (build/main.js) |
npm run dev | Build, then run (use mock .env for local testing) |
npm run watch | Watch mode for development |
npm test | Run test suite |
npm run test:watch | Run tests in watch mode |
npm run inspector | Launch MCP protocol inspector |
npm run dev:mcp-tef | Run mcp-tef locally (needs uv + Ollama) for tool-description / similarity checks |
npm run report:mcp-tef | One command: build, temporary mcp-grocy HTTP + mcp-tef, write reports/mcp-tef/<timestamp>/ (similarity JSON + SUMMARY.md) |
Optional: mcp-tef (local tool evaluation)
When you change tool descriptions or add tools, you can run StacklokLabs/mcp-tef against Ollama (no cloud API key required):
-
Install uv and start Ollama; pull a small model, e.g.
ollama pull llama3.2:3b. -
Build and start mcp-grocy over HTTP in another terminal (SSE endpoint for mcp-tef):
npm run build MCP_HTTP_TRANSPORT_ONLY=true ENABLE_HTTP_SERVER=true HTTP_SERVER_PORT=8790 npm start -
Start mcp-tef:
npm run dev:mcp-tef -
Open
http://127.0.0.1:8000/docsand point workflows athttp://127.0.0.1:8790/mcp/sse(or your port).
The first run clones mcp-tef into .cache/mcp-tef (ignored by git). Override the Ollama model with MCP_TEF_OLLAMA_MODEL, the listen port with MCP_TEF_PORT, or the clone ref with MCP_TEF_REF.
One-shot report (no manual API calls):
npm run report:mcp-tef
Writes under reports/mcp-tef/<timestamp>/:
REPORT.mdβ human-readable: tools by domain, flagged pairs as a markdown table (short tool names, similarity %).REPORT.htmlβ same pairs in a simple table; open in a browser if you prefer.SUMMARY.mdβ one-screen pointer + counts.similarity.jsonβ full API response (matrix, composite ids).
Uses ephemeral ports 8792 (mcp-grocy) and 8020 (mcp-tef) by default (MCP_GROCY_HTTP_PORT, MCP_TEF_REPORT_PORT to override). If you do not set MCP_GROCY_YAML, the script drops a temporary mcp-grocy.yaml next to the report by copying mcp-grocy.yaml.example with every enabled: false flipped to true, so tools/list is complete for analysis.
Add --with-recommendations for LLM suggestions on flagged pairs, or --quality for per-tool quality scoring (slow; both need Ollama). The report calls mcp-tefβs similarity API with transport: sse against /mcp/sse (current mcp-tef request shape). Default similarity threshold is 0.9 (set SIMILARITY_THRESHOLD=0.85 for the previous, noisier report).
Optional per-tool title and meta (β MCP _meta) can be set in definitions when they add real signal; otherwise clients use name only.
Debugging
Use the MCP inspector to debug protocol interactions:
npm run inspector
This launches a web interface for testing MCP tools and viewing protocol messages.
π€ Contributing
This is an opinionated fork focused on LLM usability and workflow reliability. Contributions are welcome but must align with the core philosophy:
β Welcome Contributions
- Bug fixes and reliability improvements
- Better error handling and validation
- Documentation improvements
- Test coverage enhancements
- Performance optimizations
β Contributions Requiring Discussion
- New tool additions (must demonstrate clear LLM workflow benefits)
- API design changes that increase complexity
- Features that expose raw Grocy API behavior
Development Workflow
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Run
npm testand ensure all tests pass - Submit a pull request with clear description
π License
This project is licensed under the MIT License.
π Made for reliable household management with LLMs
Prioritizing workflow efficiency over feature completeness
