Kroger MCP Server

Integrates Kroger's public API with Claude so meal plan grocery lists can be added directly to your Kroger cart.

Tools

Tool	What it does
kroger_find_store	Find nearby Kroger stores by ZIP code, returns location_id
kroger_search_products	Search the product catalog, returns UPC + price + aisle
kroger_add_to_cart	Add a single product by UPC to your cart
kroger_add_grocery_list	Search + add an entire grocery list in one shot
kroger_clear_auth	Clear stored tokens (if you need to re-authenticate)

Setup

Step 1 — Register your app at Kroger Developer Portal

1. Go to https://developer.kroger.com
2. Click Register App
3. Fill in:
   • App Name: Meal Plan Assistant (or anything)
   • Redirect URI: http://localhost:8080/callback
   • Scopes: product.compact, cart.basic:write, profile.compact
4. Copy your Client ID and Client Secret

Step 2 — Install dependencies

cd kroger_mcp
python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

Step 3 — Set environment variables

export KROGER_CLIENT_ID=your_client_id_here
export KROGER_CLIENT_SECRET=your_client_secret_here
export KROGER_REDIRECT_URI=http://localhost:8080/callback

Add these to your shell profile (~/.zshrc or ~/.bashrc) so they persist.

Step 4 — Connect to Claude

Add to your Claude MCP config (usually ~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "kroger": {
      "command": "/path/to/kroger_mcp/venv/bin/python",
      "args": ["/path/to/kroger_mcp/server.py"],
      "env": {
        "KROGER_CLIENT_ID": "your_client_id",
        "KROGER_CLIENT_SECRET": "your_client_secret",
        "KROGER_REDIRECT_URI": "http://localhost:8080/callback"
      }
    }
  }
}

Restart Claude Desktop after saving.

First Use — OAuth Login

The first time you ask Claude to add items to your cart:

1. Your browser will open to Kroger's login page
2. Log in with your Kroger account
3. Paste the redirect URL back into the terminal
4. Done — tokens are saved at ~/.kroger_mcp_tokens.json

After that, Claude can add to your cart silently using the stored refresh token.

Example Flow

Once connected, you can say to Claude:

"Find my nearest Kroger store and add this week's grocery list to my cart"

Claude will:

1. Call kroger_find_store with your ZIP code
2. Call kroger_add_grocery_list with all the items
3. Report back what was added, what was skipped, and any issues

Security Notes

• Your Client ID and Secret are yours — registered under your account
• Tokens are stored locally at ~/.kroger_mcp_tokens.json (permissions: 600)
• No third-party code involved — direct calls to Kroger's official API
• kroger_clear_auth removes all stored tokens if needed

Troubleshooting

"Missing environment variables" — Set KROGER_CLIENT_ID and KROGER_CLIENT_SECRET

"Authorization expired" — Retry the operation; the server will refresh automatically

"No matching product found" — Try a shorter search term (e.g., "spinach" instead of "Private Selection Baby Spinach")

Rate limits (HTTP 429) — Kroger limits requests; wait 30 seconds and retry