Skip to content
Back to search

kroger-mcp

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cupofowls--kroger-mcp/badge.svg)](/listings/cupofowls--kroger-mcp)

HTML

<a href="/listings/cupofowls--kroger-mcp"><img src="/api/listings/cupofowls--kroger-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

You will need Kroger API credentials (free from [Kroger Developer Portal](https://developer.kroger.com/)). Visit the [Kroger Developer Portal](https://developer.kroger.com/manage/apps/register) to: 1. Create a developer account 2. Register your application 3. Get 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. 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-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"
      }
    }
  }
}

Option 3: Installing From PyPI

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

# Or install with pip
pip install kroger-mcp

Option 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

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

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 343 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # 🛒 Kroger MCP Server 🛍️ -- FastMCP for Kroger Shopping
  2. A [FastMCP](https://github.com/jlowin/fastmcp) server that provides AI assistants like Claude with access to Kroger's grocery shopping functionality through the Model Context Protocol ([MCP](https://docs.anthropic.com/en/docs/agents-and-tools/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](https://github.com/CupOfOwls/kroger-api) python library.
  3. 📚 **Docs:** https://cupofowls.github.io/kroger-api/building-ai-agents/agent-lab — build an AI agent with kroger-mcp, and the full tool reference.
  4. ## 📺 Demo
  5. Using Claude with this MCP server to search for stores, find products, and add items to your cart:
  6. https://github.com/user-attachments/assets/69055f5f-04f5-4ec1-96ac-330aa288fbd1
  7. ## Changelog
  8. A changelog with recent changes is [here](CHANGELOG.md).
  9. ## 🚀 Quick Start
  10. ### Prerequisites
  11. You will need Kroger API credentials (free from [Kroger Developer Portal](https://developer.kroger.com/)).
  12. Visit the [Kroger Developer Portal](https://developer.kroger.com/manage/apps/register) to:
  13. 1. Create a developer account
  14. 2. Register your application
  15. 3. Get your `CLIENT_ID`, `CLIENT_SECRET`, and set your `REDIRECT_URI`
  16. 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.
  17. ### Installation
  18. ##### ⚠️ macOS users must use installation Option 2 ⚠️
  19. #### Option 1: Using uvx with Claude Desktop (Recommended)
  20. Once published to PyPI, you can use uvx to run the package directly without cloning the repository:
  21. Edit Claude Desktop's configuration file:
  22. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  23. **Linux**: `~/.config/Claude/claude_desktop_config.json`
  24. **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
  25. ```json
  26. {
  27. "mcpServers": {
  28. "kroger": {
  29. "command": "uvx",
  30. "args": [
  31. "kroger-mcp"
  32. ],
  33. "env": {
  34. "KROGER_CLIENT_ID": "your_client_id",
  35. "KROGER_CLIENT_SECRET": "your_client_secret",
  36. "KROGER_REDIRECT_URI": "http://localhost:8000/callback",
  37. "KROGER_USER_ZIP_CODE": "10001"
  38. }
  39. }
  40. }
  41. }
  42. ```
  43. Benefits of this method:
  44. - Automatically installs the package from PyPI if needed
  45. - Creates an isolated environment for running the server
  46. - Makes it easy to stay updated with the latest version
  47. - Doesn't require maintaining a local repository clone
  48. #### Option 2: Using uv with a Local Clone
  49. First, clone locally:
  50. ```bash
  51. git clone https://github.com/CupOfOwls/kroger-mcp
  52. ```
  53. Then, edit Claude Desktop's configuration file:
  54. ```json
  55. {
  56. "mcpServers": {
  57. "kroger": {
  58. "command": "uv",
  59. "args": [
  60. "--directory",
  61. "/path/to/cloned/kroger-mcp",
  62. "run",
  63. "kroger-mcp"
  64. ],
  65. "env": {
  66. "KROGER_CLIENT_ID": "your_client_id",
  67. "KROGER_CLIENT_SECRET": "your_client_secret",
  68. "KROGER_REDIRECT_URI": "http://localhost:8000/callback",
  69. "KROGER_USER_ZIP_CODE": "10001"
  70. }
  71. }
  72. }
  73. }
  74. ```
  75. #### Option 3: Installing From PyPI
  76. ```bash
  77. # Install with uv (recommended)
  78. uv pip install kroger-mcp
  79. # Or install with pip
  80. pip install kroger-mcp
  81. ```
  82. #### Option 4: Installing From Source
  83. ```bash
  84. # Clone the repository
  85. git clone https://github.com/CupOfOwls/kroger-mcp
  86. cd kroger-mcp
  87. # Install with uv (recommended)
  88. uv sync
  89. # Or install with pip
  90. pip install -e .
  91. ```
  92. ### Configuration
  93. 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):
  94. ```bash
  95. # Required: Your Kroger API credentials
  96. KROGER_CLIENT_ID=your_client_id_here
  97. KROGER_CLIENT_SECRET=your_client_secret_here
  98. KROGER_REDIRECT_URI=http://localhost:8000/callback
  99. # Optional: Default zip code for location searches
  100. KROGER_USER_ZIP_CODE=90274
  101. # Optional: The scopes the user grants at sign-in (default: product.compact cart.basic:write).
  102. # Add profile.compact for get_user_profile, but only if your app is registered for the Identity API.
  103. # KROGER_USER_SCOPES=product.compact cart.basic:write profile.compact
  104. ```
  105. ### Running the Server
  106. ```bash
  107. # With uv (recommended)
  108. uv run kroger-mcp
  109. # With uvx (directly from PyPI without installation)
  110. uvx kroger-mcp
  111. # Or with Python directly
  112. python server.py
  113. # Options such as an HTTP transport (see kroger-mcp --help)
  114. uvx kroger-mcp --transport streamable-http --port 8000
  115. # With FastMCP CLI for development
  116. fastmcp dev server.py --with-editable .
  117. ```
  118. ## 🛠️ Features
  119. ### 💬 Built-In MCP Prompts
  120. - **Shopping Path**: Find optimal path through store for a grocery list
  121. - **Pharmacy Check**: Check if pharmacy at preferred location is open
  122. - **Store Selection**: Help user set their preferred Kroger store
  123. - **Recipe Shopping**: Find recipes and add ingredients to cart
  124. ### 📚 Available Tools
  125. #### Location Tools
  126. | Tool | Description | Auth Required |
  127. |------|-------------|---------------|
  128. | `search_locations` | Find Kroger stores near a zip code | No |
  129. | `get_location_details` | Get detailed information about a specific store | No |
  130. | `set_preferred_location` | Set a preferred store for future operations | No |
  131. | `get_preferred_location` | Get the currently set preferred store | No |
  132. | `check_location_exists` | Verify if a location ID is valid | No |
  133. #### Product Tools
  134. | Tool | Description | Auth Required |
  135. |------|-------------|---------------|
  136. | `search_products` | Search for products by name, brand, or other criteria | No |
  137. | `bulk_search_products` | Run up to 25 product searches in a single call | No |
  138. | `get_product_details` | Get detailed product information including pricing | No |
  139. | `search_products_by_id` | Find products by their specific product ID | No |
  140. | `get_product_images` | Get product images from specific perspective (front, back, etc.) | No |
  141. #### Cart Tools
  142. | Tool | Description | Auth Required |
  143. |------|-------------|---------------|
  144. | `add_items_to_cart` | Add a single item to cart | Yes |
  145. | `bulk_add_to_cart` | Add multiple items to cart in one operation | Yes |
  146. | `view_current_cart` | View items currently in your local cart tracking | No |
  147. | `remove_from_cart` | Remove items from local cart tracking | No |
  148. | `clear_current_cart` | Clear all items from local cart tracking | No |
  149. | `mark_order_placed` | Move current cart to order history | No |
  150. | `view_order_history` | View history of placed orders | No |
  151. #### Information Tools
  152. | Tool | Description | Auth Required |
  153. |------|-------------|---------------|
  154. | `list_chains` | Get all Kroger-owned chains | No |
  155. | `get_chain_details` | Get details about a specific chain | No |
  156. | `check_chain_exists` | Check if a chain exists | No |
  157. | `list_departments` | Get all store departments | No |
  158. | `get_department_details` | Get details about a specific department | No |
  159. | `check_department_exists` | Check if a department exists | No |
  160. #### Profile Tools
  161. | Tool | Description | Auth Required |
  162. |------|-------------|---------------|
  163. | `get_user_profile` | Get authenticated user's profile information | Yes |
  164. | `test_authentication` | Check that the user is signed in and the token has not expired, refreshing it if it has | No |
  165. | `get_authentication_info` | Get detailed authentication status | No |
  166. | `force_reauthenticate` | Delete the saved sign-in, so the user can sign in again | No |
  167. `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.
  168. #### Utility Tools
  169. | Tool | Description | Auth Required |
  170. |------|-------------|---------------|
  171. | `get_current_datetime` | Get current system date and time | No |
  172. ### 🧰 Local-Only Cart Tracking
  173. Since the Kroger API doesn't provide cart viewing functionality, this server maintains local tracking:
  174. #### Local Cart Storage
  175. - **File**: `kroger_cart.json`
  176. - **Contents**: Current cart items with timestamps
  177. - **Automatic**: Created and updated automatically
  178. #### Order History
  179. - **File**: `kroger_order_history.json`
  180. - **Contents**: Historical orders with placement timestamps
  181. - **Usage**: Move completed carts to history with `mark_order_placed`
  182. #### Where these files live
  183. State files (cart, order history, preferences) and OAuth tokens are stored in the first matching location:
  184. 1. `$KROGER_TOKEN_DIR`, if you set that environment variable
  185. 2. `$XDG_DATA_HOME/kroger-mcp/` (defaults to `~/.local/share/kroger-mcp/`) on macOS/Linux
  186. 3. `%APPDATA%\kroger-mcp\` on Windows
  187. 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.
  188. 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.
  189. ### ⚡ Concurrent calls
  190. 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.
  191. ### ⚠️ Error Handling
  192. A tool that fails returns an MCP error result (`isError: true`), so the assistant can see what went wrong and correct its next call:
  193. - **Text content**: what went wrong, followed by `Next step:` and what to do about it, often naming the tool to call.
  194. - **Structured content**: an `error` object with a stable `type`, the `message`, the `next_step`, the `tool`, and every detail the [kroger-api](https://github.com/CupOfOwls/kroger-api) package has about a Kroger API error: `status_code`, Kroger's `kroger_code` and `kroger_message`, the request `method` and `url`, the `correlation_id`, a `hint`, and the `response_body`.
  195. | `type` | When |
  196. |--------|------|
  197. | `invalid_arguments` | An argument breaks the tool's input schema (wrong pattern, out of range, unknown name). `errors` lists each one. No request is sent. |
  198. | `invalid_parameter` | kroger-api rejected a value the schema cannot check, such as a search term of more than 8 words. No request is sent. |
  199. | `authentication_required` | The user is not signed in, or the sign-in expired and could not be renewed. |
  200. | `location_required` | A product tool got no `location_id` and no preferred location is set. |
  201. | `bad_request`, `authentication_error`, `permission_denied`, `not_found`, `rate_limited`, `server_error` | The Kroger API answered 400, 401, 403, 404, 429, or 5xx. |
  202. | `connection_error`, `timeout` | The Kroger API could not be reached, or did not answer within 30 seconds. |
  203. | `configuration_error` | A setting such as `KROGER_CLIENT_ID` is missing or invalid. Fix the server configuration and restart it. |
  204. | `local_state_error` | A cart, order history, or preferences file could not be read or written. |
  205. 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.
  206. 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](https://cupofowls.github.io/kroger-api/reference/mcp-tools#error-results).
  207. ### 🚧 Kroger Public API Limitations
  208. - **View Only**: The `remove_from_cart` and `clear_current_cart` tools ONLY affect local tracking, not the actual Kroger cart
  209. - **Local Sync**: Use these tools only when the user has already removed items from their cart in the Kroger app/website
  210. - **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.
  211. | API | Version | Rate Limit | Notes |
  212. |-----|---------|------------|-------|
  213. | **Authorization** | 1.0.13 | No specific limit | Token management |
  214. | **Products** | 1.2.4 | 10,000 calls/day | Search and product details |
  215. | **Locations** | 1.2.2 | 1,600 calls/day per endpoint | Store locations and details |
  216. | **Cart** | 1.2.3 | 5,000 calls/day | Add/manage cart items |
  217. | **Identity** | 1.2.3 | 5,000 calls/day | User profile information |
  218. **Note:** Rate limits are enforced per endpoint, not per operation. You can distribute calls across operations using the same endpoint as needed.
  219. ## 🏫 Basic Workflow
  220. 1. **Set up a preferred location**:
  221. ```
  222. User: "Find Kroger stores near 90274"
  223. Assistant: [Uses search_locations tool]
  224. User: "Set the first one as my preferred location"
  225. Assistant: [Uses set_preferred_location tool]
  226. ```
  227. 2. **Search and add products**:
  228. ```
  229. User: "Add milk to my cart"
  230. Assistant: [Uses search_products, then add_items_to_cart]
  231. User: "Add bread, eggs, and cheese to my cart"
  232. Assistant: [Uses search_products for each, then bulk_add_to_cart]
  233. ```
  234. 3. **Manage cart and orders**:
  235. ```
  236. User: "What's in my cart?"
  237. Assistant: [Uses view_current_cart tool to see local memory]
  238. User: "I placed the order on the Kroger website"
  239. Assistant: [Uses mark_order_placed tool, moving current cart to the order history]
  240. ```
  241. ## 🍪 OAuth2 Authentication
  242. 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.
  243. ## 🤝 Contributing
  244. 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.
  245. ## 📄 License
  246. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  247. ## ⚠️ Disclaimer
  248. This is an unofficial MCP server for the Kroger Public API. It is not affiliated with, endorsed by, or sponsored by Kroger.
  249. For questions about the Kroger API, visit the [Kroger Developer Portal](https://developer.kroger.com/) or read the [kroger-api](https://github.com/CupOfOwls/kroger-api) package documentation.
  250. ---
  251. <a href="https://mseep.ai/app/cupofowls-kroger-mcp"><img src="https://mseep.net/pr/cupofowls-kroger-mcp-badge.png" alt="MseeP.ai Security Assessment Badge" height="90"></a>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.