# Hermes Grocy MCP

Hermes Grocy MCP is an MCP server for Claude Code that integrates assistants with a self-hosted Grocy instance. Manages home inventory, groceries, barcode lookups, chores, and shopping lists.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5 repo stars
- Author: rusty4444
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/rusty4444/grocy-mcp
- Updated: 2026-08-01
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/hermes-grocy-mcp

## What it does

This server exposes tools to interact directly with the Grocy household ERP API. It searches inventory items, resolves Grocycodes and barcodes, tracks stock levels, and monitors expiring or missing groceries.

Write tools apply modifications immediately. The assistant can consume supplies, log restocks, manage shopping list entries, check off recurring chores, and update arbitrary entity objects via JSON.

Private setups require `GROCY_API_KEY` configured in client settings alongside `GROCY_BASE_URL`. Unauthenticated connections fall back to read-only queries against the public Grocy demo instance.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `GROCY_BASE_URL`, `GROCY_API_KEY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env GROCY_BASE_URL=<GROCY_BASE_URL> --env GROCY_API_KEY=<GROCY_API_KEY> --transport stdio hermes-grocy-mcp -- uvx hermes-grocy-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from hermes-grocy-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add hermes-grocy-mcp --env GROCY_BASE_URL=<GROCY_BASE_URL> --env GROCY_API_KEY=<GROCY_API_KEY> -- uvx hermes-grocy-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from hermes-grocy-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "hermes-grocy-mcp": {
            "command": "uvx",
            "args": [
                "hermes-grocy-mcp"
            ],
            "env": {
                "GROCY_BASE_URL": "<GROCY_BASE_URL>",
                "GROCY_API_KEY": "<GROCY_API_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from hermes-grocy-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "hermes-grocy-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "hermes-grocy-mcp"
            ],
            "env": {
                "GROCY_BASE_URL": "<GROCY_BASE_URL>",
                "GROCY_API_KEY": "<GROCY_API_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from hermes-grocy-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e GROCY_BASE_URL=<GROCY_BASE_URL> -e GROCY_API_KEY=<GROCY_API_KEY> hermes-grocy-mcp uvx hermes-grocy-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from hermes-grocy-mcp <command>

## When to use it
- check stock levels and find expired food items in Grocy
- add, consume, or inventory grocery supplies
- lookup products by barcode or Grocycode
- mark chores as completed and inspect household tasks

## Example prompts
- Check volatile stock in Grocy and list anything overdue
- Consume 1 unit of milk and update current inventory
- Add eggs and butter to my main shopping list

## Similar
- [linkfox-shopee-store-product](https://affpapa.org/en/nevibecode/skills/linkfox-shopee-store-product.md) — skill · 237 installs
- [hermes-history-ingest](https://affpapa.org/en/nevibecode/skills/hermes-history-ingest.md) — skill · 2500 installs
- [cli-anything-hermes](https://affpapa.org/en/nevibecode/skills/cli-anything-hermes.md) — skill · 314 installs
- [Hermes Action Bridge](https://affpapa.org/en/nevibecode/mcp/hermes-action-bridge.md) — MCP server · ★ 7 repo stars
- [hermes-voice-setup](https://affpapa.org/en/nevibecode/skills/hermes-voice-setup.md) — skill · ★ 732 repo stars
- [EquipDash](https://affpapa.org/en/nevibecode/mcp/equipdash.md) — MCP server · 4381 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
