🛒 Kroger MCP服务器🛍️ -- 用于克罗格购物的FastMCP
📺 演示
使用Claude和此MCP服务器搜索商店、查找产品并将商品添加到购物车中：
https://github.com/user-attachments/assets/69055f5f-04f5-4ec1-96ac-330aa288fbd1
更新日志
包含最近更改的更改日志是 这里.
🚀 快速开始
先决条件
您需要Kroger API证书（免费 Kroger开发者门户). 访问 Kroger开发者门户 致：
- 创建开发人员帐户
- 注册您的应用程序
- 得到你的
CLIENT_ID,CLIENT_SECRET，并设置您的REDIRECT_URI
第一次运行需要用户身份验证的工具时，系统会提示您通过web浏览器授权您的应用程序。您正在授予以下权限 您自己的注册应用程序不向任何第三方。
安装
⚠️ macOS用户必须使用安装选项2⚠️
选项1：在Claude Desktop上使用uvx（推荐）
发布到PyPI后，您可以使用uvx直接运行包，而无需克隆存储库：
编辑Claude Desktop的配置文件：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
视窗: %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 在项目根目录中创建文件，或通过JSON配置传入env值：
# 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 | 验证位置ID是否有效 | 否 |
产品工具
| 工具 | 描述 | 需要授权 |
|---|---|---|
search_products | 按名称、品牌或其他条件搜索产品 | 否 |
get_product_details | 获取包括定价在内的详细产品信息 | 否 |
search_products_by_id | 按特定产品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 | 获取克罗格所有的连锁店 | 否 |
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 | 获取当前系统日期和时间 | 否 |
🧰 仅限本地购物车跟踪
由于Kroger API不提供购物车查看功能，因此此服务器维护本地跟踪：
本地购物车存储
- 文件:
kroger_cart.json - 目录：带有时间戳的当前购物车商品
- 自动：自动创建和更新
订单历史
- 文件:
kroger_order_history.json - 目录：带有放置时间戳的历史订单
- 用法：使用将已完成的购物车移动到历史记录中
mark_order_placed
🚧 Kroger公共API限制
- 仅查看：The
remove_from_cart和clear_current_cart工具仅影响本地跟踪，不影响实际的Kroger购物车 - 本地同步：仅当用户已从Kroger应用程序/网站的购物车中删除商品时，才使用这些工具
- 单向的：物品可以添加到克罗格购物车中，但不能通过公共API移除。合作伙伴API将允许这些事情，但这需要与克罗格签订合同。
| API | 版本 | 费率限制 | 注释 |
|---|---|---|---|
| 授权 | 1.0.13 | 无具体限制 | 代币管理 |
| 产品 | 1.2.4 | 10000次/天 | 搜索和产品详细信息 |
| 位置 | 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]🍪 OAuth2身份验证
当Claude尝试修改您的Kroger帐户时，系统会要求您在浏览器中插入一个链接，该链接将处理身份验证并允许Claude在购物车中添加/删除商品。在尝试将此链接粘贴到浏览器以启动身份验证之前，请确保您已经创建了Kroger帐户（这与您的Kroger开发帐户不同）。
🤝 贡献
欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
⚠️ 免责声明
这是克罗格公共API的非官方MCP服务器。它不隶属于克罗格，也不受克罗格的支持或赞助。