🛒 Сервер Kroger MCP 🛍️ -- FastMCP для Kroger Shopping

Сервер FastMCP , который предоставляет помощникам ИИ, таким как Клод, бесперебойный доступ к функционалу покупок продуктов Kroger через Model Context Protocol ( MCP ). Этот сервер позволяет помощникам ИИ находить магазины, искать продукты, управлять корзинами покупок и получать доступ к полным данным о продуктах Kroger через библиотеку Python kroger-api .

📺 Демо

Использование Claude с этим MCP-сервером для поиска магазинов, поиска товаров и добавления товаров в корзину:

Related MCP server: mcp-carrefour

🚀 Быстрый старт

Предпосылки

Вам понадобятся учетные данные Kroger API (бесплатно с портала разработчиков Kroger ). Посетите портал разработчиков Kroger , чтобы:

1. Создать учетную запись разработчика

2. Зарегистрируйте свою заявку

3. Получите ваш CLIENT_ID , CLIENT_SECRET и установите ваш REDIRECT_URI

При первом запуске инструмента, требующего аутентификации пользователя, вам будет предложено авторизовать свое приложение через веб-браузер. Вы предоставляете разрешение своему зарегистрированному приложению , а не какой-либо третьей стороне.

Установка

Вариант 1: Использование uvx с Claude Desktop (рекомендуется)

После публикации в PyPI вы можете использовать uvx для непосредственного запуска пакета без клонирования репозитория:

Отредактируйте файл конфигурации Claude Desktop:

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

Преимущества этого метода:

• При необходимости автоматически устанавливает пакет из PyPI

• Создает изолированную среду для работы сервера

• Позволяет легко оставаться в курсе последних версий

• Не требует поддержания локального клона репозитория.

Вариант 2: Использование UV с локальным клоном

Сначала клонируем локально:

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

Затем отредактируйте файл конфигурации Claude Desktop:

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

Вариант 3: Установка из PyPI

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

# Or install with pip
pip install kroger-mcp

Вариант 4: Установка из исходного кода

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

Конфигурация

Создайте файл .env в корневом каталоге проекта или передайте значения env через конфигурацию JSON:

# 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

Запуск сервера

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

🛠️ Особенности

💬 Встроенные подсказки MCP

• Путь покупок : найдите оптимальный путь по магазину для списка покупок

• Проверка аптеки : проверьте, открыта ли аптека в выбранном вами месте.

• Выбор магазина : Помогите пользователю выбрать предпочтительный магазин Kroger.

• Покупка рецептов : найдите рецепты и добавьте ингредиенты в корзину

📚 Доступные инструменты

Инструменты определения местоположения

Инструменты продукта

Инструменты для корзины

Информационные инструменты

Инструменты профиля

Вспомогательные инструменты

🧰 Локальное отслеживание корзины

Поскольку API Kroger не предоставляет функциональность просмотра корзины, этот сервер поддерживает локальное отслеживание:

Локальное хранилище корзины

• Файл : kroger_cart.json

• Содержимое : Текущие товары в корзине с временными метками

• Автоматически : Создается и обновляется автоматически

История заказов

• Файл : kroger_order_history.json

• Содержание : Исторические заказы с отметками времени размещения

• Использование : Переместить заполненные корзины в историю с помощью mark_order_placed

🚧 Ограничения публичного API Kroger

• Только просмотр : инструменты remove_from_cart и clear_current_cart влияют ТОЛЬКО на локальное отслеживание, а не на фактическую корзину Kroger.

• Локальная синхронизация : используйте эти инструменты только в том случае, если пользователь уже удалил товары из своей корзины в приложении/на сайте Kroger.

• Односторонний : предметы можно добавлять в корзину Kroger, но нельзя удалять через Public API. API-интерфейс Partner позволяет это делать, но для этого требуется заключить контракт с Kroger.

Примечание: Ограничения скорости применяются к конечной точке, а не к операции. Вы можете распределять вызовы между операциями, используя ту же конечную точку по мере необходимости.

🏫 Базовый рабочий процесс

1. Укажите предпочтительное местоположение :

   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]

2. Поиск и добавление продуктов :

   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]

3. Управление корзиной и заказами :

   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]

🤝 Вклад

Вклады приветствуются! Не стесняйтесь отправлять запрос на извлечение. Для крупных изменений сначала откройте тему, чтобы обсудить, что вы хотели бы изменить.

📄 Лицензия

Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE .

⚠️ Отказ от ответственности

Это неофициальный сервер MCP для Kroger Public API. Он не связан, не одобрен и не спонсируется Kroger.

Если у вас есть вопросы по API Kroger, посетите портал разработчиков Kroger или ознакомьтесь с документацией по пакету kroger-api .