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

Name: Kroger MCP Server
Author: CupOfOwls

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

📺 Демо

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

Демо-версия MCP от Kroger

Related MCP server: Agora MCP

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

Предпосылки

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

Создать учетную запись разработчика
Зарегистрируйте свою заявку
Получите ваш 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.
Покупка рецептов : найдите рецепты и добавьте ингредиенты в корзину

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

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

Инструмент	Описание	Требуется аутентификация
`search_locations`	Найти магазины Kroger рядом с почтовым индексом	Нет
`get_location_details`	Получите подробную информацию о конкретном магазине	Нет
`set_preferred_location`	Установите предпочтительный магазин для будущих операций	Нет
`get_preferred_location`	Получить текущий предпочитаемый магазин	Нет
`check_location_exists`	Проверьте, действителен ли идентификатор местоположения	Нет

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

Инструмент	Описание	Требуется аутентификация
`search_products`	Поиск продуктов по названию, бренду или другим критериям	Нет
`get_product_details`	Получите подробную информацию о продукте, включая цены	Нет
`search_products_by_id`	Найти продукты по их конкретному идентификатору продукта	Нет
`get_product_images`	Получите изображения продукта с определенной точки зрения (спереди, сзади и т. д.)	Нет

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

Инструмент	Описание	Требуется аутентификация
`add_items_to_cart`	Добавить один товар в корзину	Да
`bulk_add_to_cart`	Добавьте несколько товаров в корзину за одну операцию	Да
`view_current_cart`	Просмотр товаров, которые в данный момент находятся в вашей локальной корзине для отслеживания	Нет
`remove_from_cart`	Удалить элементы из локального отслеживания корзины	Нет
`clear_current_cart`	Удалить все товары из локального отслеживания корзины	Нет
`mark_order_placed`	Переместить текущую корзину в историю заказов	Нет
`view_order_history`	Посмотреть историю размещенных заказов	Нет

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

Инструмент	Описание	Требуется аутентификация
`list_chains`	Получить все сети, принадлежащие Kroger	Нет
`get_chain_details`	Получить подробную информацию о конкретной сети	Нет
`check_chain_exists`	Проверить, существует ли цепочка	Нет
`list_departments`	Получить все отделы магазина	Нет
`get_department_details`	Получить подробную информацию о конкретном отделе	Нет
`check_department_exists`	Проверьте, существует ли отдел	Нет

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

Инструмент	Описание	Требуется аутентификация
`get_user_profile`	Получить информацию о профиле аутентифицированного пользователя	Да
`test_authentication`	Проверьте, действителен ли токен аутентификации.	Да
`get_authentication_info`	Получить подробный статус аутентификации	Да
`force_reauthenticate`	Очистить токены и принудительно провести повторную аутентификацию	Нет

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

Инструмент	Описание	Требуется аутентификация
`get_current_datetime`	Получить текущую системную дату и время	Нет

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

Поскольку 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.

API	Версия	Ограничение скорости	Примечания
Авторизация	1.0.13	Нет определенного ограничения	Управление токенами
Продукция	1.2.4	10 000 звонков/день	Поиск и сведения о продукте
Места	1.2.2	1600 вызовов/день на конечную точку	Расположение и подробности магазинов
Корзина	1.2.3	5000 звонков/день	Добавить/управлять товарами в корзине
Личность	1.2.3	5000 звонков/день	Информация профиля пользователя

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

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

Укажите предпочтительное местоположение :
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]
Поиск и добавление продуктов :
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]
Управление корзиной и заказами :
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 .

Kroger MCP Server