Kroger MCP 服务器

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

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

📺 演示

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

Kroger MCP 演示

🚀 快速入门

先决条件

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

创建开发者帐户
注册您的应用程序
获取您的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 商店
食谱购物：查找食谱并将食材添加到购物车

📚 可用工具

定位工具

工具	描述	需要授权
`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 个电话	用户个人资料信息

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

🏫 基本工作流程

设置首选位置：
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]

🤝 贡献

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

📄 许可证

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

⚠️ 免责声明

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

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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

FastMCP 服务器通过模型上下文协议为 Claude 等 AI 助手提供对 Kroger 杂货店购物功能的无缝访问，从而实现商店查找、产品搜索和购物车管理。

Related MCP Servers

Exa MCP Server
exa-labs
A
security
A
license
A
quality
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
Last updated -
1
2,167
1,631
TypeScript
MIT License
lunchmoney-mcp
leafeye
A
security
A
license
A
quality
An MCP server that lets AI assistants interact with your Lunchmoney data, enabling natural language queries about transactions, budgets, and spending patterns.
Last updated -
4
3
8
TypeScript
MIT License
Trading Simulator MCP Server
recallnet
-
security
F
license
-
quality
An MCP server that enables AI models like Claude to interact with the Trading Simulator API for checking balances, viewing prices, and executing trades with automatic chain detection.
Last updated -
TypeScript
Agora MCP
Fewsats
-
security
F
license
-
quality
An MCP server that connects AI assistants to SearchAgora, enabling users to search for, discover, and purchase products across the web through natural language conversations.
Last updated -
1
Python

View all related MCP servers

Kroger MCP Server