🛒 Kroger MCP 服务器 🛍️ -- 用于 Kroger 购物的 FastMCP

一个FastMCP服务器，通过模型上下文协议 ( MCP )，为 Claude 这样的 AI 助手提供无缝访问 Kroger 杂货店购物功能的权限。该服务器使 AI 助手能够通过kroger-api Python 库查找商店、搜索商品、管理购物车并访问 Kroger 全面的杂货店数据。

📺 演示

使用 Claude 和此 MCP 服务器搜索商店、查找产品并将商品添加到购物车：

Related MCP server: mcp-carrefour

🚀 快速入门

先决条件

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

1. 创建开发者帐户

2. 注册您的应用程序

3. 获取您的CLIENT_ID 、 CLIENT_SECRET ，并设置您的REDIRECT_URI

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

安装

选项 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文件或通过 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 商店

• 食谱购物：查找食谱并将食材添加到购物车

📚 可用工具

定位工具

产品工具

购物车工具

信息工具

配置文件工具

实用工具

🧰 仅限本地购物车追踪

由于 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 签订合同。

**注意：**速率限制是针对每个端点强制执行的，而不是针对每个操作。您可以根据需要使用同一端点在不同操作之间分配调用。

🏫 基本工作流程

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]

🤝 贡献

欢迎贡献代码！欢迎提交 Pull 请求。对于重大变更，请先提交一个 issue 来讨论您想要修改的内容。

📄 许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

⚠️ 免责声明

这是 Kroger 公共 API 的非官方 MCP 服务器。它与 Kroger 没有任何关联，也未获得其认可或赞助。

如对 Kroger API 有疑问，请访问Kroger 开发者门户或阅读kroger-api包文档。