Kroger

You can run a Kroger MCP Server to give AI assistants access to Kroger’s grocery shopping features, including finding stores, searching products, managing a cart, and accessing Kroger data through the MCP interface. This lets you orchestrate shopping tasks with natural language from an embedded AI assistant while keeping Kroger data actions under your control.

How to use

To use the Kroger MCP Server in an MCP client, you connect to a local or remote MCP runner and issue the built‑in tools described here. You can set a preferred Kroger location, search for products, add items to a local cart, view your cart, and move completed carts into an order history. The server handles authentication with Kroger and maintains local cart state to help you simulate a user workflow without relying on the Kroger website for every step.

How to install

Prerequisites: ensure you have Python and a working internet connection. You will also need Kroger API credentials (CLIENT_ID, CLIENT_SECRET) from the Kroger Developer Portal.

Choose one of the following installation flows that matches your setup.

Option 1: Using uvx with Claude Desktop (Recommended) populate the Claude Desktop configuration with the following MCP entry for Kroger.

{
  "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"
      }
    }
  }
}

Option 2: Using uv with a Local Clone

Clone the repository locally, then configure Claude Desktop to run the local copy with uv.

git clone https://github.com/CupOfOwls/kroger-mcp

Option 3: Installing From PyPI

Install the MCP server from PyPI and run with uv or uvx.

# Install with uv (recommended)
uv pip install kroger-mcp

# Or install with pip
pip install kroger-mcp

Option 4: Installing From Source

If you prefer to run from source, clone the repo and install the package in editable mode.

# 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

Create a .env file in your project root or provide env values via the MCP config JSON. Required: Kroger credentials and redirect URI.

# 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

Running the Server

Run the MCP server using your chosen method. The final start command depends on your installation flow.

# With uv (recommended)
uv run kroger-mcp

# With uvx (directly from PyPI without installation)
uvx kroger-mcp

# Or with Python directly
python server.py

# For development with FastMCP CLI
fastmcp dev server.py --with-editable .

Available tools

search_locations

Find Kroger stores near a zip code

get_location_details

Get detailed information about a specific store

set_preferred_location

Set a preferred Kroger store for future operations

get_preferred_location

Get the currently set preferred store

check_location_exists

Verify if a location ID is valid

search_products

Search for products by name, brand, or other criteria

get_product_details

Get detailed product information including pricing

search_products_by_id

Find products by their specific product ID

get_product_images

Get product images from specific perspective (front, back, etc.)

add_items_to_cart

Add a single item to cart (requires authentication)

bulk_add_to_cart

Add multiple items to cart in one operation (requires authentication)

view_current_cart

View items currently in your local cart tracking

remove_from_cart

Remove items from local cart tracking

clear_current_cart

Clear all items from local cart tracking

mark_order_placed

Move current cart to order history

view_order_history

View history of placed orders

list_chains

Get all Kroger-owned chains

get_chain_details

Get details about a specific chain

check_chain_exists

Check if a chain exists

list_departments

Get all store departments

get_department_details

Get details about a specific department

check_department_exists

Check if a department exists

get_user_profile

Get authenticated user's profile information

test_authentication

Test if authentication token is valid

get_authentication_info

Get detailed authentication status

force_reauthenticate

Clear tokens and force re-authentication

get_current_datetime

Get current system date and time