MCP server for the Kroger Public APIs (Products, Locations, Cart, Identity) and optional Partner Catalog V2
  • TypeScript 62.1%
  • JavaScript 37.9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-06 15:44:04 -05:00
src 1.1.0: compact output by default (verbose flag), value fields ($/30 g protein), default store, UPC-A input/output, complete_authentication for remote-browser logins, request timeout + safe retries, per-scope client-token cache 2026-11-06 15:33:07 -05:00
.gitignore Kroger MCP server: Products, Locations, Cart, Identity + optional Partner Catalog V2 (stdio, TypeScript) 2026-11-06 15:25:17 -05:00
LICENSE Add MIT license 2026-11-06 15:44:04 -05:00
package-lock.json Kroger MCP server: Products, Locations, Cart, Identity + optional Partner Catalog V2 (stdio, TypeScript) 2026-11-06 15:25:17 -05:00
package.json Add MIT license 2026-11-06 15:44:04 -05:00
README.md Add MIT license 2026-11-06 15:44:04 -05:00
tsconfig.json Kroger MCP server: Products, Locations, Cart, Identity + optional Partner Catalog V2 (stdio, TypeScript) 2026-11-06 15:25:17 -05:00

Kroger MCP Server

An MCP (Model Context Protocol) server for the Kroger API, covering the Public APIs (Products, Locations, Cart, Identity) and, optionally, the Partner Catalog V2 API.

Works with Claude Desktop, Claude Code, and any other MCP client that supports stdio servers.

Prerequisites

  1. Node.js 18+
  2. A Kroger developer app. Register at developer.kroger.com:
    • Create an account, then create an application (Production environment).
    • Note the Client ID and Client Secret.
    • Add a redirect URL of http://localhost:8779/callback (needed for the cart/profile login flow).
    • Enable the scopes you plan to use: product.compact, cart.basic:write, profile.compact.

Install & build

cd kroger-mcp
npm install
npm run build

Configure your MCP client

Claude Desktop (claude_desktop_config.json) or Claude Code (.mcp.json):

{
  "mcpServers": {
    "kroger": {
      "command": "node",
      "args": ["/absolute/path/to/kroger-mcp/dist/index.js"],
      "env": {
        "KROGER_CLIENT_ID": "your-client-id",
        "KROGER_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Environment variables

Variable Default Purpose
KROGER_CLIENT_ID — Required. Your app's client ID.
KROGER_CLIENT_SECRET — Required. Your app's client secret.
KROGER_ENVIRONMENT production production (api.kroger.com) or certification (api-ce.kroger.com).
KROGER_REDIRECT_URI http://localhost:8779/callback Must exactly match a redirect URL registered on your app.
KROGER_USER_SCOPES cart.basic:write profile.compact Scopes requested during customer login.
KROGER_CLIENT_SCOPE product.compact Scope for client-credentials tokens (products/locations).
KROGER_ENABLE_PARTNER_CATALOG false Set true to expose Catalog V2 tools (requires a Kroger partner agreement).
KROGER_TOKEN_DIR ~/.kroger-mcp Where customer tokens are cached (file mode 600).
KROGER_BANNER — Chain branding on the login screen (e.g. ralphs, frys, kingsoopers).
KROGER_DEFAULT_LOCATION_ID — Store used when search_products / get_product are called without locationId, so prices and stock come back by default.
KROGER_TIMEOUT_MS 20000 Per-request timeout for Kroger API calls.

Tools

Products & Locations (no login needed — uses your app credentials)

  • search_products — fuzzy search by term, brand, or productId; with a store (locationId or KROGER_DEFAULT_LOCATION_ID) includes price, stock level, and aisle location
  • get_product — one product by Kroger productId or scanned 12-digit UPC-A barcode
  • search_locations — find stores near a zip code or lat/long, filter by chain/department
  • get_location, list_chains, get_chain, list_departments, get_department

Compact output. Product and location tools return a compact summary by default (~20–30× smaller than Kroger's raw JSON, which carries every image URL and allergen record). Pass verbose: true for the raw response. A compact product looks like:

{
  "productId": "0001111010716",
  "barcode": "011110107169",
  "description": "Kroger® Vanilla Blended Nonfat Greek Yogurt Tub",
  "size": "32 oz",
  "soldBy": "UNIT",
  "price": { "regular": 3.69 },
  "stock": "HIGH",
  "aisle": "DAIRY, bay 12, side L",
  "nutrition": { "serving": "0.67 Cup US", "servingsPerPackage": 5, "calories": 140, "protein_g": 15, "carbs_g": 18 },
  "value": { "protein_g": 75, "basis": "per package (label servings)", "usd_per_30g_protein": 1.48 }
}
  • barcode is the scannable UPC-A (or EAN-13), with check digit — Kroger productIds omit it. Omitted for items sold by weight, whose scale labels embed the price.
  • value uses the promo price when there is one. For items sold by weight the price is per size (e.g. "1 lb"), so protein is computed for that amount, not the average package.

Customer login (for cart & profile)

  • start_authentication — returns a login URL and starts a local callback server (PKCE). Open the URL, sign in with a Kroger account, approve access.
  • complete_authentication — for when the browser isn't on the machine running the server (phone, another PC): the final redirect to localhost fails to load there, so paste that page's full URL (...?code=...&state=...) and the server finishes the login.
  • get_authentication_status — check whether login is pending / complete / failed
  • logout — clear the stored session

Tokens are cached to disk, so the login survives restarts; access tokens are refreshed automatically using the refresh token.

Cart & Identity (require a completed login)

  • add_to_cart — add items (productId or 12-digit UPC-A, quantity, PICKUP/DELIVERY) to the customer's cart. The public Cart API can only add items — view/remove happens on kroger.com.
  • get_profile — the customer's profile (profile id with the public profile.compact scope; more fields with partner scopes)

Partner Catalog V2 (only when KROGER_ENABLE_PARTNER_CATALOG=true)

  • catalog_search — catalog product data for a location + fulfillment type
  • catalog_inventory — stock levels, fulfillment status, promotions
  • catalog_deleted_items — products disabled within a date range (max 2 days)

These require a Kroger partner agreement and the urn:com:kroger:partner:catalog:products:read scope on your app; they will return 401/403 otherwise.

Rate limits (public APIs)

  • Products: 10,000 calls/day
  • Locations: 1,600 calls/day per endpoint
  • Cart & Identity: 5,000 calls/day each

Reliability

Requests time out after KROGER_TIMEOUT_MS. 429 responses are retried (honouring Retry-After) for every method; 5xx, network errors and timeouts are retried only for GET, so an add_to_cart is never sent twice. Up to 3 attempts.

Example prompts

  • "Find Kroger stores near 40204 and pick the closest one."
  • "Search for oat milk at store 01400943 and show prices."
  • "Log me into Kroger, then add 2 gallons of 2% milk to my pickup cart."

Notes

  • Location IDs are 8 digits (3-digit division + 5-digit store number). Kroger product IDs are 13 digits (the UPC without its check digit, zero-padded); tools also accept a scanned 12-digit UPC-A.
  • A 403 missing required scopes error means the scope isn't enabled on your app in the Kroger developer portal.

License

MIT — see LICENSE.