{
  "markdown": "# Grocy MCP\n\n<!-- mcp-name: io.github.rusty4444/hermes-grocy-mcp -->\n\nA Model Context Protocol (MCP) server for [Grocy](https://grocy.info/), the self-hosted household ERP for groceries, inventory, chores, batteries, recipes, tasks, and shopping lists.\n\nThis server focuses on AI-friendly household operations that are awkward through generic REST clients:\n\n- Inspect Grocy system/version status\n- List, search, and inspect products\n- Read current stock, volatile stock, product stock details, and individual stock entries\n- List current shopping list items and add/remove products from shopping lists\n- Look up products by barcode/Grocycode\n- List and inspect any `/api/objects/{entity}` entity\n- Create/update generic entity objects from JSON\n- Add, consume, and inventory product stock\n- Add/remove product amounts from shopping lists\n\n## Why this exists\n\nGrocy has a strong REST API, but MCP coverage is sparse and usually either incomplete or tightly coupled to one client's workflow. This package gives Hermes, Claude Desktop, Cursor, and other MCP clients a small, explicit, documented tool surface.\n\n## Installation\n\n```bash\npipx install git+https://github.com/rusty4444/grocy-mcp.git\n```\n\nOr from a checkout:\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n```\n\n## Configuration\n\nThe server reads configuration from environment variables:\n\n| Variable | Required | Default | Description |\n|---|---:|---|---|\n| `GROCY_BASE_URL` | No | `https://demo.grocy.info` | Grocy base URL, with or without `/api` |\n| `GROCY_API_KEY` | No for public/demo read-only instances, yes for private/write access | unset | Grocy API key sent as `GROCY-API-KEY` |\n| `GROCY_TIMEOUT` | No | `20` | HTTP timeout in seconds |\n\nGrocy API keys are managed in Grocy under **Manage API keys**. The API accepts the `GROCY-API-KEY` header.\n\n## MCP client config\n\n```json\n{\n  \"mcpServers\": {\n    \"grocy\": {\n      \"command\": \"grocy-mcp\",\n      \"env\": {\n        \"GROCY_BASE_URL\": \"https://grocy.example.com\",\n        \"GROCY_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n## Tools\n\n| Tool | Purpose |\n|---|---|\n| `grocy_system_info` | Grocy version and runtime details |\n| `grocy_list_products` | List configured products |\n| `grocy_search_products` | Search products by name/description |\n| `grocy_get_product` | Fetch one product object |\n| `grocy_lookup_product_by_barcode` | Resolve a barcode/Grocycode |\n| `grocy_stock_overview` | Current stock rows |\n| `grocy_volatile_stock` | Due, overdue, expired, or missing products |\n| `grocy_product_stock_details` | Detailed stock state for one product |\n| `grocy_product_stock_entries` | Individual stock entries in next-use order |\n| `grocy_common_entities` | Common generic entity names useful with CRUD tools |\n| `grocy_list_shopping_lists` | Configured shopping lists |\n| `grocy_list_shopping_list_items` | Current shopping list rows, optionally filtered by list id |\n| `grocy_list_entity` | List any generic Grocy entity |\n| `grocy_get_entity_object` | Fetch any generic entity object |\n| `grocy_create_entity_object` | POST a generic entity object from JSON |\n| `grocy_update_entity_object` | PUT a generic entity object from JSON |\n| `grocy_add_stock` | Add product amount to stock |\n| `grocy_consume_stock` | Consume/remove product amount from stock |\n| `grocy_inventory_product` | Set product inventory amount |\n| `grocy_add_product_to_shopping_list` | Add a product to a shopping list |\n| `grocy_remove_product_from_shopping_list` | Remove a product from a shopping list |\n| `grocy_set_userfields` | Set userfield values on an entity object |\n| `grocy_list_chores` | List chores including computed next-due times |\n| `grocy_execute_chore` | Execute (mark done) a chore, optionally backdated |\n| `grocy_list_tasks` | List tasks |\n\n## Development and validation\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -e '.[dev]'\nruff check .\npytest\npython scripts/live_readonly_test.py\n```\n\nThe live read-only test defaults to `https://demo.grocy.info`, avoiding mutations on shared infrastructure. It has been validated against Grocy API 4.6.0. Use a private Grocy instance plus `GROCY_API_KEY` for write-path testing.\n\n## Safety\n\nWrite-capable tools directly mutate Grocy data. Prefer read-only tools when using public demos. Keep `GROCY_API_KEY` in MCP client environment config or a secret manager, never in source control.\n",
  "bytes": 4397,
  "sha": "eb47ac0eb06d0d0567b5d199997e3b313be72c3bbf6bbe26bd61decbd9734f7b",
  "repo_slug": "rusty4444/grocy-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rusty4444_hermes_grocy_mcp_d2563b30/readme"
}