# kroger-mcp
## 基本信息
- Slug: `cupofowls-kroger-mcp`
- Source: modelscope
- Publisher: @CupOfOwls/kroger-mcp
- Categories: ecommerce-and-retail / app-automation
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@CupOfOwls/kroger-mcp
## 简介
暂无描述。
## 安装提示

```bash
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: ```bash git clone https://github.com/CupOfOwls/kroger-mcp
```

## MCP Server 详情

#  Kroger MCP Server  -- FastMCP for Kroger Shopping

![Logo](media/harper_logo.jpeg)

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.

##  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

## Changelog
A changelog with recent changes is [here](CHANGELOG.md).

##  Quick Start

### 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`

```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:
```bash
git clone https://github.com/CupOfOwls/kroger-mcp
```

Then, edit Claude Desktop's configuration file:

```json
{
  "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

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

# Or install with pip
pip install kroger-mcp
```

#### Option 4: Installing From Source

```bash
# 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:

```bash
# 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

```bash
# 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 .
```


##  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 |
|------|-------------|---------------|
| `search_locations` | Find Kroger stores near a zip code | No |
| `get_location_details` | Get detailed information about a specific store | No |
| `set_preferred_location` | Set a preferred store for future operations | No |
| `get_preferred_location` | Get the currently set preferred store | No |
| `check_location_exists` | Verify if a location ID is valid | No |

#### Product Tools

| Tool | Description | Auth Required |
|------|-------------|---------------|
| `search_products` | Search for products by name, brand, or other criteria | No |
| `get_product_details` | Get detailed product information including pricing | No |
| `search_products_by_id` | Find products by their specific product ID | No |
| `get_product_images` | Get product images from specific perspective (front, back, etc.) | No |

#### Cart Tools

| Tool | Description | Auth Required |
|------|-------------|---------------|
| `add_items_to_cart` | Add a single item to cart | Yes |
| `bulk_add_to_cart` | Add multiple items to cart in one operation | Yes |
| `view_current_cart` | View items currently in your local cart tracking | No |
| `remove_from_cart` | Remove items from local cart tracking | No |
| `clear_current_cart` | Clear all items from local cart tracking | No |
| `mark_order_placed` | Move current cart to order history | No |
| `view_order_history` | View history of placed orders | No |

#### Information Tools

| Tool | Description | Auth Required |
|------|----------…