Kroger MCP server for AI agents

The Kroger MCP Server enables AI assistants to interact with Kroger's grocery shopping platform through the Model Context Protocol. This server allows for finding stores, searching products, managing shopping carts, and accessing Kroger's grocery data via a streamlined interface.

Getting Started

Prerequisites

To use this server, you'll need Kroger API credentials from the Kroger Developer Portal:

Create a developer account
Register your application
Obtain your CLIENT_ID, CLIENT_SECRET, and set your REDIRECT_URI

The first time you run a tool requiring user authentication, you'll be prompted to authorize your app through your web browser.

Installation Options

Using uvx with Claude Desktop (Recommended)

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

Using uv with a Local Clone

First, clone the repository:

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

Then, 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"
      }
    }
  }
}

Installing From PyPI

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

# Or install with pip
pip install kroger-mcp

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

Create a .env file in your project root or pass in env values via the JSON config:

# 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

# With uv (recommended)
uv run kroger-mcp

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

# Or with Python directly
python server.py

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

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 store for future operations
get_preferred_location: Get the currently set preferred store
check_location_exists: Verify if a location ID is valid

Product Tools

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.)

Cart Tools

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

Information Tools

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

Profile Tools

get_user_profile: Get authenticated user's profile information (requires authentication)
test_authentication: Test if authentication token is valid (requires authentication)
get_authentication_info: Get detailed authentication status (requires authentication)
force_reauthenticate: Clear tokens and force re-authentication

Utility Tools

get_current_datetime: Get current system date and time

Local-Only Cart Tracking

Since the Kroger API doesn't provide cart viewing functionality, this server maintains local tracking:

Local Cart Storage: Maintained in kroger_cart.json
Order History: Stored in kroger_order_history.json

API Limitations

The Kroger Public API has some limitations:

remove_from_cart and clear_current_cart tools ONLY affect local tracking, not the actual Kroger cart
Items can be added to the Kroger cart but not removed through the Public API

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]

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect