Kroger

This MCP server wraps the Kroger API and exposes Kroger data and cart actions to large language models via a standard Model Context Protocol interface. You can search for products, locate stores by ZIP code, retrieve product details, and manage a user’s Kroger cart through OAuth2-enabled operations. This guide provides practical steps to install, configure, and run the server, and then use it with an MCP client.

How to use

You will run the server locally and connect an MCP client to it using standard stdio transport. The server exposes these core capabilities: find Kroger stores by ZIP code, search for products at a specific store, retrieve detailed product information, and add items to a user’s Kroger cart (the cart operations require user authorization). Start the server, then perform actions through your MCP client by invoking the available tools in the order that matches your task (for example, locate a store, search for a product, and add it to a cart after completing user authorization). Ensure you have completed the OAuth2 flow to authorize cart operations before attempting actions that modify a user’s cart.

How to install

# Prerequisites: Python and a working internet connection
# 1) Create a project directory and navigate into it
# 2) Create a virtual environment (optional but recommended)
# 3) Install required packages
pip install requests mcp
# 4) Place your configuration in a config.py file (see configuration section for details)
# 5) Run the server
python server.py

Additional sections

Configuration and runtime details are provided below. Follow these steps to enable OAuth2 authentication, store lookups, and product search through the MCP server.

Configuration prerequisites include API credentials for Kroger and OAuth2 settings. You will set a client ID, client secret, and a redirect URI for the authorization flow. You will also configure a user refresh token to allow cart operations to persist across server restarts.

Security and tokens are handled through standard OAuth2 flows. Keep your client secret and refresh tokens secure and rotate them as needed.

Notes on usage and troubleshooting: ensure the OAuth2 redirect URI you register with Kroger matches the one you configure locally. If an access token expires, the server will attempt to refresh it using the refresh token. If refresh fails, re-authentication is required.

Example workflow for cart operations after initial authorization: locate a store, search for a product at that location, and add the product to the cart. If the user has not authorized cart access yet, you will receive an error indicating that user authentication is required and you should complete the OAuth2 authorization flow.

Available tools

find_stores

Find Kroger store locations by ZIP code and return nearby stores with IDs. Optional radius and limit parameters can refine results.

search_products

Search Kroger products by keyword at a specified store location. Returns a list of matching products with IDs and metadata.

get_product

Retrieve detailed information for a product by product ID and location, including price, size, stock status, and fulfillment options.

add_to_cart

Add a product to the user’s Kroger cart. Requires user authentication; uses the product ID, quantity, and location ID.