Kroger MCP Server
Kroger MCP Server lets an AI assistant search Kroger stores/products and perform authenticated grocery cart operations through Kroger's API.
Search and inspect store locations, zip defaults, preferred stores, chains, departments, and validity checks.
Search products by term or ID, get product details/pricing/availability, and fetch product images.
Add single or bulk items to the Kroger cart with pickup or delivery modality, requiring OAuth.
View and manage local cart tracking and order history; remove/clear only local tracking, not the actual Kroger cart.
Manage Kroger OAuth sign-in/status, reauthenticate, and retrieve user profile when properly scoped.
Get current date/time and use built-in workflows/prompts for shopping, pharmacy checks, store selection, and recipe shopping.
Leverages the kroger-api Python library to interact with Kroger's API for finding stores, searching products, managing shopping carts, and accessing grocery data
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Kroger MCP Server search for organic milk near me"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🛒 Kroger MCP Server 🛍️ -- FastMCP for Kroger Shopping
A FastMCP server that provides AI assistants like Claude with access to Kroger's grocery shopping functionality through the Model Context Protocol (MCP). This server enables AI assistants to find stores, search products, manage shopping carts, and access Kroger's comprehensive grocery data via the kroger-api python library.
📚 Docs: https://cupofowls.github.io/kroger-api/building-ai-agents/agent-lab — build an AI agent with kroger-mcp, and the full tool reference.
📺 Demo
Using Claude with this MCP server to search for stores, find products, and add items to your cart:
https://github.com/user-attachments/assets/69055f5f-04f5-4ec1-96ac-330aa288fbd1
Related MCP server: mcp-carrefour
Changelog
A changelog with recent changes is here.
🚀 Quick Start
Prerequisites
You will need Kroger API credentials (free from Kroger Developer Portal). Visit the Kroger Developer Portal to:
Create a developer account
Register your application
Get your
CLIENT_ID,CLIENT_SECRET, and set yourREDIRECT_URI
The first time you run a tool requiring user authentication, you'll be prompted to authorize your app through your web browser. You're granting permission to your own registered app, not to any third party.
Installation
⚠️ macOS users must use installation Option 2 ⚠️
Option 1: Using uvx with Claude Desktop (Recommended)
Once published to PyPI, you can use uvx to run the package directly without cloning the repository:
Edit Claude Desktop's configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"kroger": {
"command": "uvx",
"args": [
"kroger-mcp"
],
"env": {
"KROGER_CLIENT_ID": "your_client_id",
"KROGER_CLIENT_SECRET": "your_client_secret",
"KROGER_REDIRECT_URI": "http://localhost:8000/callback",
"KROGER_USER_ZIP_CODE": "10001"
}
}
}
}Benefits of this method:
Automatically installs the package from PyPI if needed
Creates an isolated environment for running the server
Makes it easy to stay updated with the latest version
Doesn't require maintaining a local repository clone
Option 2: Using uv with a Local Clone
First, clone locally:
git clone https://github.com/CupOfOwls/kroger-mcpThen, edit Claude Desktop's configuration file:
{
"mcpServers": {
"kroger": {
"command": "uv",
"args": [
"--directory",
"/path/to/cloned/kroger-mcp",
"run",
"kroger-mcp"
],
"env": {
"KROGER_CLIENT_ID": "your_client_id",
"KROGER_CLIENT_SECRET": "your_client_secret",
"KROGER_REDIRECT_URI": "http://localhost:8000/callback",
"KROGER_USER_ZIP_CODE": "10001"
}
}
}
}Option 3: Installing From PyPI
# Install with uv (recommended)
uv pip install kroger-mcp
# Or install with pip
pip install kroger-mcpOption 4: Installing From Source
# Clone the repository
git clone https://github.com/CupOfOwls/kroger-mcp
cd kroger-mcp
# Install with uv (recommended)
uv sync
# Or install with pip
pip install -e .Configuration
Pass the settings in the env block of your MCP client's JSON config, or put them in a .env file in the directory you start the server from (only its KROGER_* settings are read):
# Required: Your Kroger API credentials
KROGER_CLIENT_ID=your_client_id_here
KROGER_CLIENT_SECRET=your_client_secret_here
KROGER_REDIRECT_URI=http://localhost:8000/callback
# Optional: Default zip code for location searches
KROGER_USER_ZIP_CODE=90274
# Optional: The scopes the user grants at sign-in (default: product.compact cart.basic:write).
# Add profile.compact for get_user_profile, but only if your app is registered for the Identity API.
# KROGER_USER_SCOPES=product.compact cart.basic:write profile.compactRunning the Server
# With uv (recommended)
uv run kroger-mcp
# With uvx (directly from PyPI without installation)
uvx kroger-mcp
# Or with Python directly
python server.py
# Options such as an HTTP transport (see kroger-mcp --help)
uvx kroger-mcp --transport streamable-http --port 8000
# With FastMCP CLI for development
fastmcp dev server.py --with-editable .🛠️ Features
💬 Built-In MCP Prompts
Shopping Path: Find optimal path through store for a grocery list
Pharmacy Check: Check if pharmacy at preferred location is open
Store Selection: Help user set their preferred Kroger store
Recipe Shopping: Find recipes and add ingredients to cart
📚 Available Tools
Location Tools
Tool | Description | Auth Required |
| Find Kroger stores near a zip code | No |
| Get detailed information about a specific store | No |
| Set a preferred store for future operations | No |
| Get the currently set preferred store | No |
| Verify if a location ID is valid | No |
Product Tools
Tool | Description | Auth Required |
| Search for products by name, brand, or other criteria | No |
| Run up to 25 product searches in a single call | No |
| Get detailed product information including pricing | No |
| Find products by their specific product ID | No |
| Get product images from specific perspective (front, back, etc.) | No |
Cart Tools
Tool | Description | Auth Required |
| Add a single item to cart | Yes |
| Add multiple items to cart in one operation | Yes |
| View items currently in your local cart tracking | No |
| Remove items from local cart tracking | No |
| Clear all items from local cart tracking | No |
| Move current cart to order history | No |
| View history of placed orders | No |
Information Tools
Tool | Description | Auth Required |
| Get all Kroger-owned chains | No |
| Get details about a specific chain | No |
| Check if a chain exists | No |
| Get all store departments | No |
| Get details about a specific department | No |
| Check if a department exists | No |
Profile Tools
Tool | Description | Auth Required |
| Get authenticated user's profile information | Yes |
| Check that the user is signed in and the token has not expired, refreshing it if it has | No |
| Get detailed authentication status | No |
| Delete the saved sign-in, so the user can sign in again | No |
start_authentication asks the user to grant product.compact and cart.basic:write, which the cart tools need. get_user_profile also needs profile.compact, from the Identity API. An app may request only the scopes of the API products it is registered for, and Kroger refuses the whole sign-in with invalid_scope when one is missing, so profile.compact is not requested by default. To use get_user_profile, register the Identity API for your app in the Kroger Developer Portal, set KROGER_USER_SCOPES to product.compact cart.basic:write profile.compact, restart the server, and sign in again.
Utility Tools
Tool | Description | Auth Required |
| Get current system date and time | No |
🧰 Local-Only Cart Tracking
Since the Kroger API doesn't provide cart viewing functionality, this server maintains local tracking:
Local Cart Storage
File:
kroger_cart.jsonContents: Current cart items with timestamps
Automatic: Created and updated automatically
Order History
File:
kroger_order_history.jsonContents: Historical orders with placement timestamps
Usage: Move completed carts to history with
mark_order_placed
Where these files live
State files (cart, order history, preferences) and OAuth tokens are stored in the first matching location:
$KROGER_TOKEN_DIR, if you set that environment variable$XDG_DATA_HOME/kroger-mcp/(defaults to~/.local/share/kroger-mcp/) on macOS/Linux%APPDATA%\kroger-mcp\on Windows
They are never written to the current working directory, which may be read-only or change between sessions under MCP hosts like Claude Desktop. Files from older versions that live in the working directory are migrated automatically on first use.
Several server processes can share the directory, for example one for Claude Desktop and one for Claude Code. Each change to a state file, and each renewal of the sign-in, holds a lock on that file (a .lock file beside it), so the processes do not overwrite each other's changes or sign each other out.
⚡ Concurrent calls
Each tool that calls the Kroger API or reads a state file runs in a worker thread, so a slow Kroger request holds up only its own call. The assistant's other calls go on, and so do the other clients of a server that uses the streamable-http or sse transport. Cancelling a call answers at once, but the request it already sent still finishes: a cancelled add_items_to_cart can still add the items.
⚠️ Error Handling
A tool that fails returns an MCP error result (isError: true), so the assistant can see what went wrong and correct its next call:
Text content: what went wrong, followed by
Next step:and what to do about it, often naming the tool to call.Structured content: an
errorobject with a stabletype, themessage, thenext_step, thetool, and every detail the kroger-api package has about a Kroger API error:status_code, Kroger'skroger_codeandkroger_message, the requestmethodandurl, thecorrelation_id, ahint, and theresponse_body.
| When |
| An argument breaks the tool's input schema (wrong pattern, out of range, unknown name). |
| kroger-api rejected a value the schema cannot check, such as a search term of more than 8 words. No request is sent. |
| The user is not signed in, or the sign-in expired and could not be renewed. |
| A product tool got no |
| The Kroger API answered 400, 401, 403, 404, 429, or 5xx. |
| The Kroger API could not be reached, or did not answer within 30 seconds. |
| A setting such as |
| A cart, order history, or preferences file could not be read or written. |
A cart add that times out, loses its connection after the request may have been sent, or gets a 5xx has outcome_unknown: true. Kroger may have added the items anyway, so the next step says to have the user check their cart before adding again, instead of retrying.
A search that finds nothing is not an error: it returns count: 0 and a message. The full list of error types is in the MCP tools reference.
🚧 Kroger Public API Limitations
View Only: The
remove_from_cartandclear_current_carttools ONLY affect local tracking, not the actual Kroger cartLocal Sync: Use these tools only when the user has already removed items from their cart in the Kroger app/website
One-Way: Items can be added to the Kroger cart but not removed through the Public API. The Partner API would allow these things, but that requires entering a contract with Kroger.
API | Version | Rate Limit | Notes |
Authorization | 1.0.13 | No specific limit | Token management |
Products | 1.2.4 | 10,000 calls/day | Search and product details |
Locations | 1.2.2 | 1,600 calls/day per endpoint | Store locations and details |
Cart | 1.2.3 | 5,000 calls/day | Add/manage cart items |
Identity | 1.2.3 | 5,000 calls/day | User profile information |
Note: Rate limits are enforced per endpoint, not per operation. You can distribute calls across operations using the same endpoint as needed.
🏫 Basic Workflow
Set up a preferred location:
User: "Find Kroger stores near 90274" Assistant: [Uses search_locations tool] User: "Set the first one as my preferred location" Assistant: [Uses set_preferred_location tool]Search and add products:
User: "Add milk to my cart" Assistant: [Uses search_products, then add_items_to_cart] User: "Add bread, eggs, and cheese to my cart" Assistant: [Uses search_products for each, then bulk_add_to_cart]Manage cart and orders:
User: "What's in my cart?" Assistant: [Uses view_current_cart tool to see local memory] User: "I placed the order on the Kroger website" Assistant: [Uses mark_order_placed tool, moving current cart to the order history]
🍪 OAuth2 Authentication
When Claude attempts to modify your Kroger account, you will be asked to insert a link into your browser that will handle authentication and allow Claude to add/remove items from your cart. Ensure that you have already made a Kroger account (this is different than your Kroger development account) before attempting to paste this link into your browser to initiate authentication.
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
⚠️ Disclaimer
This is an unofficial MCP server for the Kroger Public API. It is not affiliated with, endorsed by, or sponsored by Kroger.
For questions about the Kroger API, visit the Kroger Developer Portal or read the kroger-api package documentation.
Available Tools
31 toolsadd_items_to_cartA
Add a single item to the user's Kroger cart and track it locally.
If the user doesn't specifically indicate a preference for pickup or delivery, you should ask them which modality they prefer before calling this tool.
Inputs: product_id (required), modality, quantity. Returns: object
bulk_add_to_cartA
Add multiple items to the user's Kroger cart in a single operation.
If the user doesn't specifically indicate a preference for pickup or delivery, you should ask them which modality they prefer before calling this tool.
Inputs: items (required). Returns: object
bulk_search_productsB
Search for multiple products in a single tool call to reduce round-trips.
Inputs: searches (required), location_id. Returns: object
check_chain_existsB
Check if a chain exists in the Kroger system.
Inputs: chain_name (required). Returns: object
check_department_existsA
Check if a department exists in the Kroger system.
Inputs: department_id (required). Returns: object
check_location_existsB
Check if a location exists in the Kroger system.
Inputs: location_id (required). Returns: object
clear_current_cartA
Clear all items from the local cart tracking only.
IMPORTANT: This tool CANNOT remove items from the actual Kroger cart in the app/website. It only clears our local tracking. The user must remove items from their actual cart through the Kroger app or website themselves.
Use this tool only when:
The user has already cleared their Kroger cart through the app/website
You need to update the local tracking to reflect that change
Or when the local tracking is out of sync with the actual cart
Returns: Dictionary confirming the local cart tracking was cleared
Inputs: no named parameters. Returns: object
complete_authenticationA
Complete the OAuth flow using the redirect URL from Kroger.
After opening the auth URL in your browser and authorizing the app, you'll be redirected to a callback URL. Copy that entire URL and pass it to this tool to complete the authentication process.
Inputs: redirect_url (required). Returns: object
force_reauthenticateA
Force re-authentication by clearing the current authentication token. Use this if you're having authentication issues or need to log in as a different user.
This deletes the saved user token. The local cart tracking and order history are kept.
Returns: Dictionary indicating the re-authentication was initiated
Inputs: no named parameters. Returns: object
get_authentication_infoA
Get information about the current authentication state and token.
A user who is not signed in is a normal result (authenticated false), not an error.
Returns: Dictionary containing authentication information
Inputs: no named parameters. Returns: object
get_chain_detailsC
Get detailed information about a specific Kroger chain.
Inputs: chain_name (required). Returns: object
get_current_datetimeA
Get the current system date and time.
This tool is useful for comparing with cart checkout dates, order history, or any other time-sensitive operations.
Returns: Dictionary containing current date and time information
Inputs: no named parameters. Returns: object
get_department_detailsC
Get detailed information about a specific department.
Inputs: department_id (required). Returns: object
get_location_detailsB
Get detailed information about a specific Kroger store location.
Inputs: location_id (required). Returns: object
get_preferred_locationA
Get the currently set preferred store location.
No preferred location is a normal result (preferred_location_id null), not an error.
Returns: Dictionary containing the preferred location information
Inputs: no named parameters. Returns: object
get_product_detailsB
Get detailed information about a specific product.
Inputs: product_id (required), location_id. Returns: object
get_product_imagesA
Get an image for a specific product from the requested perspective.
Use get_product_details first to see what perspectives are available (typically "front", "back", "left", "right").
Inputs: product_id (required), location_id, perspective.
get_user_profileA
Get the authenticated user's Kroger profile information.
The Identity API needs a sign-in that grants the profile.compact scope.
Returns: Dictionary containing user profile data
Inputs: no named parameters. Returns: object
get_user_zip_codeA
Returns user zip code, it is anticipated that by exposing this to the LLM it will choose to use it rather than generating a zip code based on system data.
Args: N/A Returns: Dictionary containing user Zip Code
Inputs: no named parameters. Returns: object
list_chainsA
Get a list of all Kroger-owned chains.
Returns: Dictionary containing chain information
Inputs: no named parameters. Returns: object
list_departmentsB
Get a list of all available departments in Kroger stores.
Returns: Dictionary containing department information
Inputs: no named parameters. Returns: object
mark_order_placedA
Mark the current cart as an order that has been placed and move it to order history. Use this after you've completed checkout on the Kroger website/app.
Inputs: order_notes. Returns: object
remove_from_cartA
Remove an item from the local cart tracking only.
IMPORTANT: This tool CANNOT remove items from the actual Kroger cart in the app/website. It only updates our local tracking to stay in sync. The user must remove the item from their actual cart through the Kroger app or website themselves.
Use this tool only when:
The user has already removed an item from their Kroger cart through the app/website
You need to update the local tracking to reflect that change
Inputs: product_id (required), modality. Returns: object
search_locationsC
Search for Kroger store locations near a zip code.
Inputs: chain, limit, zip_code, radius_in_miles. Returns: object
search_productsC
Search for products at a Kroger store.
Inputs: search_term (required), brand, limit, fulfillment, +1 more. Returns: object
search_products_by_idC
Search for products by their specific product ID.
Inputs: product_id (required), location_id. Returns: object
set_preferred_locationB
Set a preferred store location for future operations.
Inputs: location_id (required). Returns: object
start_authenticationA
Start the OAuth authentication flow with Kroger.
This tool returns a URL that the user needs to open in their browser to authenticate with Kroger. After authorization, the user will be redirected to a callback URL that they need to copy and paste back. If Kroger shows invalid_scope instead of the sign-in page, the app is not registered for one of the requested scopes (the scope field of the result, set by KROGER_USER_SCOPES in the server's configuration).
Returns: Dictionary with authorization URL, the requested scopes, and instructions
Inputs: no named parameters. Returns: object
test_authenticationA
Check whether the user is signed in and the saved token has not expired.
An expired token is refreshed if possible. The check compares the token's expiry time with the clock, so a sign-in that Kroger revoked early still reports token_valid true until a cart call fails. A user who is not signed in is a normal result (token_valid false), not an error.
Returns: Dictionary indicating authentication status
Inputs: no named parameters. Returns: object
view_current_cartA
View the current cart contents tracked locally.
Note: This tool can only see items that were added via this MCP server. The Kroger API does not provide permission to query the actual user cart contents.
Returns: Dictionary containing current cart items and summary
Inputs: no named parameters. Returns: object
view_order_historyA
View the history of placed orders.
Note: This tool can only see orders that were explicitly marked as placed via this MCP server. The Kroger API does not provide permission to query the actual order history from Kroger's systems.
Inputs: limit. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 31 tools
Most tools target distinct resources and actions (locations, products, cart, orders, chains, departments). The main overlap is between authentication/status tools and between paired check_* versus get_* detail tools, but the descriptions make the intended use clear enough to avoid serious misselection.
Almost all tools use a readable snake_case verb_noun pattern such as get_location_details, search_products, and add_items_to_cart. Minor deviations like bulk_search_products, force_reauthenticate, and mark_order_placed slightly break the pattern but remain understandable and consistent in casing.
At 31 tools, the surface is heavy for a shopping assistant MCP, with several check_*/get_* pairs and bulk variants inflating the set. The broad domain explains some of it, but many tools could be consolidated or treated as internal helpers.
Core workflows are covered: authentication, store search, product search/details, cart add/view/remove/clear, local order history, chains, departments, and profile. Gaps include no true checkout or cart-quantity update, and cart/order operations are local-only due to Kroger API limits, but the tool descriptions acknowledge these constraints.
Maintenance
Related MCP Connectors
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Hosted MCP for e-commerce: live product catalog, stock, and pricing for AI agents.
Connect e-commerce and marketing data to AI assistants via MCP.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- FlicenseNot gradedqualityFmaintenanceA Model Context Protocol server that enables AI assistants to interact with a complete e-commerce application, providing authentication, product browsing, and shopping cart management through standardized MCP tools.-
- AlicenseNot gradedqualityDmaintenanceMCP server that connects Carrefour Drive to Claude and other MCP clients, enabling product search with real prices, nutriscore, availability, and natural language cart management.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Online Boutique AI Assistant that exposes 18 e-commerce microservice functions via the Model Context Protocol, enabling any MCP client to manage products, carts, checkout, payments, and shipping.MIT
- AlicenseNot gradedqualityCmaintenanceControl your grocery cart with AI! This MCP server enables LLMs (like Claude) to search past orders, find products, and manage your shopping cart across all Loblaws-owned grocery banners.12AGPL 3.0