restrackit-pantry-mcp

A remote MCP server that turns a snapshot of a grocery receipt into an up-to-date household pantry. Talk to Claude, snap a photo of your receipt or just say what you bought or used, and it tracks quantities on your behalf — no barcode scanning, no manual data entry, no rigid expiry-date bookkeeping.

Built on top of restrackit-core, restrackit's own inventory-traceability backend, reused here purely through its public REST API — this project ships no changes to that codebase.

How it works

Claude is multimodal, so it reads the receipt photo itself: no OCR pipeline to build or maintain. For every line item it estimates a plausible expiry date and storage location — dispensa (pantry), frigo (fridge), or congelatore (freezer); other values are accepted but get a generic fallback shelf life instead of a tuned one — from general knowledge, then calls this server to persist it. restrackit-pantry-mcp is a thin, fully stateless translation layer — it holds no database of its own and defers every fact about inventory to restrackit-core.

Claude (Desktop/mobile)
   │  reads the receipt photo / listens to a spoken update
   │  estimates category + plausible expiry date per item
   ▼
restrackit-pantry-mcp (AWS Lambda + API Gateway, MCP Streamable HTTP)
   │  translates tool calls into authenticated REST requests
   ▼
restrackit-core REST API

Related MCP server: Kitchen MCP

Tools exposed

There's no dedicated "shopping list" tool — ask Claude what you're low on and it reasons over get_pantry_status in the conversation.

One-time setup

1. Create the "Home" store on restrackit-core (requires an ADMIN_ALL account):

   curl -X POST https://api.restrackit.example.com/v1/onboarding/stores \
     -H "Authorization: Bearer <admin token>" \
     -H "Content-Type: application/json" \
     -d '{"store_name": "Home", "manager": {"username": "restrackit-pantry-mcp", "email": "you@example.com"}}'

   Note down the returned store_id and temporary_password.

2. No manual Keycloak step is needed here — the onboarding call in step 1 already assigned the manager realm role and set temporary_password. That password is temporary (Keycloak's UPDATE_PASSWORD required action), so it can't be used with TokenProvider's password-grant flow as-is: log in interactively once to set a permanent password (or have an admin reset it via the Keycloak admin console / kcadm.sh), otherwise the server will fail to authenticate.

3. Copy .env.example to .env and fill in every value, including the store_id from step 1.

4. Run python scripts/setup_catalog.py to pre-populate a few starter categories and storage methods (optional — add_purchase creates anything missing on demand anyway).

Deployment

Infrastructure is defined as AWS CDK (Python) under infra/:

cd infra
uv venv .venv && source .venv/bin/activate
uv pip install --python .venv -r requirements.txt
cdk deploy \
  --parameters KeycloakUrl=... \
  --parameters KeycloakRealm=... \
  --parameters KeycloakClientId=... \
  --parameters KeycloakUsername=... \
  --parameters KeycloakPassword=... \
  --parameters RestrackitBaseUrl=... \
  --parameters RestrackitStoreId=... \
  --parameters McpAuthToken=...

Take the ApiUrl from the output and register it as a Custom Connector in Claude (Desktop/mobile), using the value of MCP_AUTH_TOKEN as its bearer token.

Development

uv sync --extra dev
uv run pytest