AI-shopping-list

This project implements a Model Context Protocol (MCP) server designed to interact with the Kroger API.

The goal is to allow AI models (like those in editors such as Cursor) to help manage QFC/Kroger shopping lists.

Setup & Configuration

Kroger Developer Portal Setup

IMPORTANT: You must register your OAuth redirect URI in the Kroger Developer Portal:

1. Go to Kroger Developer Portal
2. Navigate to your application settings
3. Add the exact redirect URI: https://ai-meal-planner-mcp.aranlucas.workers.dev/callback
4. Save the configuration

⚠️ Common Issues:

• The redirect URI must match exactly (including trailing slashes, protocol, etc.)
• Make sure your KROGER_CLIENT_ID and KROGER_CLIENT_SECRET environment variables are correctly set
• Verify that your application has the correct scopes enabled: profile.compact, cart.basic:write, product.compact

Connecting to Claude and other MCP Clients

You can connect your Remote MCP server to Claude and other MCP Clients via a local proxy.

Now that your MCP server is running, you can use the mcp-remote local proxy to connect Claude Desktop or other MCP clients to it — even though these tools aren't yet remote MCP clients, and don't support remote transport or authorization on the client side. This lets you test what an interaction with your MCP server will be like with a real MCP client.

{
  "mcpServers": {
    "ai-shopping-list": {
      "command": "pnpm",
      "args": ["dlx", "mcp-remote", "https://ai-meal-planner-mcp.aranlucas.workers.dev/mcp"]
    }
  }
}

Restart Claude Desktop after updating your config file to load the MCP Server. Once this is done, Claude will be able to make calls to your remote MCP server. You can test this by asking Claude to use one of your tools. For example: "Could you use the math tool to add 23 and 19?". Claude should invoke the tool and show the result generated by the MCP server.

Available Tools

The Kroger MCP server provides the following tools:

Shopping Cart Management

• add_to_cart - Adds products to your Kroger shopping cart
  • Parameters: items (array of products with UPC, quantity, and modality)

Store Locations

• search_locations - Searches for Kroger store locations
  • Parameters: zipCode, limit, chain (e.g., "QFC")
• get_location_details - Gets detailed information about a specific store
  • Parameters: locationId

Product Search

• search_products - Bulk search for products using multiple terms (parallel execution)
  • Parameters: terms (array of 1-10 search strings), locationId
• get_product_details - Gets detailed information about a specific product
  • Parameters: productId, locationId

User Data Management

• manage_pantry - Add, remove, or clear pantry items (action discriminator)
• manage_equipment - Add, remove, or clear kitchen equipment (action discriminator)
• mark_order_placed - Record a completed order in history

Shopping List

• manage_shopping_list - Add, remove, update, or clear shopping list items (action discriminator)
• checkout_shopping_list - Add unchecked items with UPCs to Kroger cart

AI-Powered Tools

• search_recipes_from_web - Search and extract recipes via web API
• plan_meals - AI-powered meal suggestions from pantry, equipment, and dietary preferences

MCP Prompts

The server provides guided workflow prompts for common shopping scenarios:

Shopping Assistant Prompts

• grocery_list_store_path - Helps organize your grocery list into an optimal shopping route through the store

  • Parameters: grocery_list (string)
  • Creates efficient aisle-by-aisle shopping paths

• set_preferred_store - Guides you through selecting and saving your preferred Kroger store

  • Parameters: zip_code (optional)
  • Displays nearby stores with addresses and distances

• add_recipe_to_cart - Finds a recipe and automatically adds ingredients to your cart

  • Parameters: recipe_type (default: "classic apple pie")
  • Searches for products, suggests alternatives, and bulk-adds ingredients

Features

Human-Readable Responses

All tools return formatted, easy-to-read responses instead of raw JSON:

• Products: Markdown-formatted with pricing, availability, and aisle locations
• Locations: Clean display of addresses, hours, and departments
• Weekly Deals: Clear pricing with savings amounts and valid dates

Type Safety

• Fully typed with TypeScript
• Uses OpenAPI-generated type definitions
• Zero any types throughout the codebase

Live Workers AI Reranker Test

Run the direct, opt-in smoke test against the real Workers AI reranker:

pnpm test:reranker:live

Locally, it uses the current wrangler login OAuth session. In CI, set both CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. The command is separate from pnpm test, incurs Workers AI usage, and verifies that “Whole Milk” ranks ahead of “Chocolate Milk Bar.”

References

Related Projects

• CupOfOwls/kroger-mcp - Python-based Kroger MCP implementation
  • Reference implementation for feature ideas and UX patterns
  • Includes local cart tracking workaround for API limitations
  • Built with FastMCP

Documentation

• Kroger Developer Portal - Official API documentation
• Model Context Protocol - MCP specification
• MCP Remote Proxy - Connect Claude Desktop to remote MCP servers