- TypeScript 62.1%
- JavaScript 37.9%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| src | ||
| .gitignore | ||
| LICENSE | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
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
- Node.js 18+
- 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 (locationIdorKROGER_DEFAULT_LOCATION_ID) includes price, stock level, and aisle locationget_product— one product by Kroger productId or scanned 12-digit UPC-A barcodesearch_locations— find stores near a zip code or lat/long, filter by chain/departmentget_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 }
}
barcodeis 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.valueuses the promo price when there is one. For items sold by weight the price is persize(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 tolocalhostfails 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 / failedlogout— 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 publicprofile.compactscope; more fields with partner scopes)
Partner Catalog V2 (only when KROGER_ENABLE_PARTNER_CATALOG=true)
catalog_search— catalog product data for a location + fulfillment typecatalog_inventory— stock levels, fulfillment status, promotionscatalog_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 scopeserror means the scope isn't enabled on your app in the Kroger developer portal.
License
MIT — see LICENSE.