🛒 Kroger MCP Server 🛍️ -- FastMCP for Kroger Shopping

这是一个FastMCP服务器，通过模型上下文协议（MCP）提供给像Claude这样的AI助手访问Kroger购物功能的能力。此服务器使AI助手能够查找商店、搜索产品、管理购物车并访问Kroger全面的杂货数据，通过kroger-api Python库实现。

📺 演示

使用Claude与这个MCP服务器来搜索商店、查找产品并将商品添加到您的购物车：

https://github.com/user-attachments/assets/69055f5f-04f5-4ec1-96ac-330aa288fbd1

更新日志

最近的更新记录在此处：CHANGELOG.md。

🚀 快速开始

预备条件

您需要Kroger API凭证（可从Kroger开发者门户免费获取）。 访问Kroger开发者门户以：

1. 创建一个开发者账户
2. 注册您的应用程序
3. 获取您的CLIENT_ID、CLIENT_SECRET，并设置您的REDIRECT_URI

首次运行需要用户身份验证的工具时，系统会提示您通过浏览器授权您的应用。您授予的是您自己注册的应用权限，而不是第三方。

安装

⚠️ macOS用户必须使用安装选项2 ⚠️

选项1：使用uvx与Claude桌面（推荐）

一旦发布到PyPI，您可以使用uvx直接运行包而无需克隆仓库：

编辑Claude桌面的配置文件：

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桌面的配置文件：

{
  "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": "1_0001"
      }
    }
  }
}

选项3：从PyPI安装

# 使用uv安装（推荐）
uv pip install kroger-mcp

# 或者使用pip安装
pip install kroger-mcp

选项4：从源代码安装

# 克隆仓库
git clone https://github.com/CupOfOwls/kroger-mcp
cd kroger-mcp

# 使用uv安装（推荐）
uv sync

# 或者使用pip安装
pip install -e .

配置

在项目根目录创建一个.env文件或通过JSON配置传递环境变量值：

# 必需：您的Kroger API凭证
KROGER_CLIENT_ID=your_client_id_here
KROGER_CLIENT_SECRET=your_client_secret_here
KROGER_REDIRECT_URI=http://localhost:8000/callback

# 可选：位置搜索的默认邮政编码
KROGER_USER_ZIP_CODE=90274

运行服务器

# 使用uv（推荐）
uv run kroger-mcp

# 使用uvx（直接从PyPI运行，无需安装）
uvx kroger-mcp

# 或直接使用Python
python server.py

# 使用FastMCP CLI进行开发
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	获取所有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	获取当前系统日期和时间	否

🧰 仅本地购物车跟踪

由于Kroger API不提供查看购物车的功能，此服务器维护本地跟踪：

本地购物车存储

• 文件：kroger_cart.json
• 内容：带有时间戳的当前购物车商品
• 自动：自动创建和更新

订单历史

• 文件：kroger_order_history.json
• 内容：带有下单时间戳的历史订单
• 使用：使用mark_order_placed将完成的购物车移动到历史记录

🚧 Kroger公共API限制

• 仅查看：remove_from_cart和clear_current_cart工具仅影响本地跟踪，而不影响实际的Kroger购物车
• 本地同步：仅当用户已在Kroger应用/网站上删除购物车中的商品时，才应使用这些工具
• 单向：可以通过公共API添加商品到Kroger购物车，但不能通过它删除。合作伙伴API允许这些操作，但这需要与Kroger签订合同。

API	版本	速率限制	备注
授权	1.0.13	无具体限制	令牌管理
产品	1.2.4	每天10,000次调用	搜索和产品详情
位置	1.2.2	每个端点每天1,600次调用	商店位置和详情
购物车	1.2.3	每天5,000次调用	添加/管理购物车商品
身份	1.2.3	每天5,000次调用	用户资料信息

注意：速率限制按端点执行，而非按操作。您可以根据需要在相同端点的操作之间分配调用。

🏫 基本工作流程

1. 设置首选位置：

   用户："查找90274附近的Kroger商店"
   助手：[使用search_locations工具]
   用户："将第一个设为我的首选位置"
   助手：[使用set_preferred_location工具]
   

2. 搜索并添加产品：

   用户："将牛奶添加到我的购物车"
   助手：[使用search_products，然后使用add_items_to_cart]
   
   用户："将面包、鸡蛋和奶酪添加到我的购物车"
   助手：[对每个产品使用search_products，然后使用bulk_add_to_cart]
   

3. 管理购物车和订单：

   用户："我的购物车里有什么？"
   助手：[使用view_current_cart工具查看本地记忆]
   
   用户："我在Kroger网站上完成了订单"
   助手：[使用mark_order_placed工具，将当前购物车移动到订单历史]
   

🍪 OAuth2认证

当Claude尝试修改您的Kroger账户时，系统会要求您插入一个链接到浏览器中，该链接将处理认证并允许Claude添加/移除购物车中的商品。确保您已经创建了一个Kroger账户（这不同于您的Kroger开发者账户），然后再尝试将此链接粘贴到浏览器中以启动认证。

🤝 贡献

欢迎贡献！请随时提交Pull Request。对于重大更改，请先打开一个问题讨论您想要更改的内容。

📄 许可

本项目基于MIT许可——详情见LICENSE文件。

⚠️ 免责声明

这是一个非官方的Kroger公共API MCP服务器。它未得到Kroger的认可、赞助或支持。

关于Kroger API的问题，请访问Kroger开发者门户或阅读kroger-api包文档。