English Français العربية

Hermes Grocy MCP

السجل الرسمي التجارة الإلكترونية

MCP server for Grocy household ERP inventory and shopping workflows.

الشيفرة المصدرية الموقع التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

PYPI package hermes-grocy-mcp
Claude Code 
claude mcp add hermes-grocy-mcp -e 'GROCY_BASE_URL=<GROCY_BASE_URL>' -e 'GROCY_API_KEY=<your grocy_api_key>' -- uvx hermes-grocy-mcp==0.2.1
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "hermes-grocy-mcp": {
            "command": "uvx",
            "args": [
                "hermes-grocy-mcp==0.2.1"
            ],
            "env": {
                "GROCY_BASE_URL": "<GROCY_BASE_URL>",
                "GROCY_API_KEY": "<your grocy_api_key>"
            }
        }
    }
}

متغيرات البيئة

  • GROCY_BASE_URL Grocy base URL, with or without /api
  • GROCY_API_KEY سري Grocy API key for private instances or write access

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. Grocy MCP
  2. Why this exists
  3. Installation
  4. Configuration
  5. MCP client config
  6. Tools
  7. Development and validation
  8. Safety

Grocy MCP

A Model Context Protocol (MCP) server for Grocy, the self-hosted household ERP for groceries, inventory, chores, batteries, recipes, tasks, and shopping lists.

This server focuses on AI-friendly household operations that are awkward through generic REST clients:

  • Inspect Grocy system/version status
  • List, search, and inspect products
  • Read current stock, volatile stock, product stock details, and individual stock entries
  • List current shopping list items and add/remove products from shopping lists
  • Look up products by barcode/Grocycode
  • List and inspect any /api/objects/{entity} entity
  • Create/update generic entity objects from JSON
  • Add, consume, and inventory product stock
  • Add/remove product amounts from shopping lists

Why this exists

Grocy 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.

Installation

pipx install git+https://github.com/rusty4444/grocy-mcp.git

Or from a checkout:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration

The server reads configuration from environment variables:

VariableRequiredDefaultDescription
GROCY_BASE_URLNohttps://demo.grocy.infoGrocy base URL, with or without /api
GROCY_API_KEYNo for public/demo read-only instances, yes for private/write accessunsetGrocy API key sent as GROCY-API-KEY
GROCY_TIMEOUTNo20HTTP timeout in seconds

Grocy API keys are managed in Grocy under Manage API keys. The API accepts the GROCY-API-KEY header.

MCP client config

{
  "mcpServers": {
    "grocy": {
      "command": "grocy-mcp",
      "env": {
        "GROCY_BASE_URL": "https://grocy.example.com",
        "GROCY_API_KEY": "your-api-key"
      }
    }
  }
}

Tools

ToolPurpose
grocy_system_infoGrocy version and runtime details
grocy_list_productsList configured products
grocy_search_productsSearch products by name/description
grocy_get_productFetch one product object
grocy_lookup_product_by_barcodeResolve a barcode/Grocycode
grocy_stock_overviewCurrent stock rows
grocy_volatile_stockDue, overdue, expired, or missing products
grocy_product_stock_detailsDetailed stock state for one product
grocy_product_stock_entriesIndividual stock entries in next-use order
grocy_common_entitiesCommon generic entity names useful with CRUD tools
grocy_list_shopping_listsConfigured shopping lists
grocy_list_shopping_list_itemsCurrent shopping list rows, optionally filtered by list id
grocy_list_entityList any generic Grocy entity
grocy_get_entity_objectFetch any generic entity object
grocy_create_entity_objectPOST a generic entity object from JSON
grocy_update_entity_objectPUT a generic entity object from JSON
grocy_add_stockAdd product amount to stock
grocy_consume_stockConsume/remove product amount from stock
grocy_inventory_productSet product inventory amount
grocy_add_product_to_shopping_listAdd a product to a shopping list
grocy_remove_product_from_shopping_listRemove a product from a shopping list
grocy_set_userfieldsSet userfield values on an entity object
grocy_list_choresList chores including computed next-due times
grocy_execute_choreExecute (mark done) a chore, optionally backdated
grocy_list_tasksList tasks

Development and validation

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
ruff check .
pytest
python scripts/live_readonly_test.py

The 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.

Safety

Write-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.

الأسئلة الشائعة

ما هو Hermes Grocy MCP؟

MCP server for Grocy household ERP inventory and shopping workflows.

كيف أثبّت Hermes Grocy MCP؟

يعمل على جهازك. في Claude Code: claude mcp add hermes-grocy-mcp -e 'GROCY_BASE_URL=<GROCY_BASE_URL>' -e 'GROCY_API_KEY=<your grocy_api_key>' -- uvx hermes-grocy-mcp==0.2.1. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج Hermes Grocy MCP إلى مفتاح API؟

نعم. يتطلب GROCY_API_KEY، وتضبطها في إعداداته.

هل Hermes Grocy MCP مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون Hermes Grocy MCP؟

ينشره rusty4444. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.