Family Grocery MCP

An MVP proof of concept for a family meal-planning and Kroger/King Soopers shopping assistant.

The project is intentionally split into two layers:

• references/kroger-mcp/: cloned upstream Kroger MCP reference.
• src/family_grocery_mcp/: our family-specific planning, allergy review, shopping-list, budget, and cart-prep layer.

Current MVP

This first pass works without Kroger credentials by using a small mock catalog. It can:

• Load a household profile from data/household_profile.json
• Suggest a Mediterranean-leaning weekly dinner plan
• Generate leftover lunches
• Consolidate a grocery list from selected meals
• Match grocery items to mock products
• Flag egg, peanut, and tree-nut allergy risks
• Estimate total cost against a monthly budget
• Search live Kroger/King Soopers locations and products
• Prepare a conservative approved-cart list from live product matches
• Start and complete Kroger cart OAuth
• Add only approved, non-review items to the Kroger cart after explicit confirmation
• Expose the workflow as MCP tools when dependencies are installed

Quick Demo

python3 -m family_grocery_mcp.cli demo

If running directly from the repo without installing, use:

PYTHONPATH=src python3 -m family_grocery_mcp.cli demo

Live Kroger Public API Checks

After creating .env, validate credentials without printing secrets:

PYTHONPATH=src python3 -m family_grocery_mcp.cli validate-kroger

Search nearby stores:

PYTHONPATH=src python3 -m family_grocery_mcp.cli locations --zip 80005

Search products at a selected store:

PYTHONPATH=src python3 -m family_grocery_mcp.cli products "greek yogurt" --location-id "YOUR_LOCATION_ID"

Preview the seed meal plan with live Kroger product matches:

PYTHONPATH=src python3 -m family_grocery_mcp.cli preview-live --location-id "YOUR_LOCATION_ID"

Live compact product search does not reliably include full ingredient lists, so packaged foods are marked for review by default. Raw produce, meat, and seafood can be treated as lower-risk matches, but checkout still remains manual.

MCP Server

Install dependencies once:

uv sync

Run the MCP server:

uv run family-grocery-mcp

Claude Desktop/Codex MCP config can use:

{
  "mcpServers": {
    "family-grocery": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/kkaminky/Documents/Grocery Shopper",
        "run",
        "family-grocery-mcp"
      ]
    }
  }
}

Current MCP tools include:

• plan_week
• preview_shopping
• validate_kroger
• search_kroger_locations
• search_kroger
• preview_live_shopping
• start_kroger_cart_auth
• complete_kroger_cart_auth
• kroger_cart_auth_status
• prepare_kroger_cart
• add_approved_items_to_kroger_cart
• add_single_item_to_kroger_cart

Cart OAuth and Add-To-Cart

Start cart authentication:

uv run family-grocery cart-auth-start

Open the returned URL, log in, then copy the final redirected URL and run:

uv run family-grocery cart-auth-complete "PASTE_FULL_REDIRECT_URL_HERE"

Preview what would be added:

uv run family-grocery cart-preview --dinners 2

Add only approved, non-review items to the real Kroger cart:

uv run family-grocery cart-add-approved --dinners 2 --confirm

Add one explicit test item by UPC:

uv run family-grocery cart-add-item 0000000094053 --quantity 1 --confirm

Items flagged for missing ingredient data, egg, peanut, or tree-nut risk are skipped.

Kroger Developer Setup

Create a Kroger developer app before live cart testing:

1. Go to Kroger Developer.

2. Sign in or create a developer account.

3. Open My Apps / Manage Apps and create a new application.

4. Set the OAuth redirect URI exactly to:

   http://localhost:8000/callback
   

5. Enable/request these scopes:

   product.compact
   cart.basic:write
   profile.compact
   

6. Copy the client ID and client secret into a local .env file:

   cp .env.example .env
   

   Then edit .env locally. Do not commit secrets.

The public Kroger API can add items to a cart, but it cannot fully view or remove cart contents. This assistant keeps local tracking and expects a human to review the real cart before checkout.

MCP Configuration

Once dependencies are installed, point Claude Desktop or another MCP client at:

{
  "mcpServers": {
    "family-grocery": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/kkaminky/Documents/Grocery Shopper",
        "run",
        "family-grocery-mcp"
      ],
      "env": {
        "FAMILY_GROCERY_PROFILE": "/Users/kkaminky/Documents/Grocery Shopper/data/household_profile.json",
        "KROGER_USER_ZIP_CODE": "80005"
      }
    }
  }
}

Next Build Steps

1. Import recipes from PDFs and URLs.
2. Persist approved products, substitutions, and rejected products.
3. Improve quantity/package math for produce and meat.
4. Add a small review UI for allergy uncertainty and budget tradeoffs.
5. Add recipe/meal-plan editing instead of only seed meals.