texas-grocery

🛒 Texas Grocery MCP

🤖 让 AI 帮你买菜！一个将 Claude 连接到 H-E-B 超市的 MCP 服务。

通过自然对话搜索商品、管理购物车、领取优惠券等。

⚠️ 本项目与 H-E-B 无关联。它使用非官方 Web API 和浏览器自动化操作 HEB.com；请负责任地使用，并确保使用行为符合适用的条款和法律。

---

✨ 功能

功能	描述
🏪 门店搜索	按地址或邮政编码查找 HEB 门店
🔍 商品搜索	搜索商品及其价格和库存情况
🛒 购物车管理	添加或移除商品，并通过人工确认
📋 商品详情	配料、营养成分、过敏原和警告
🎟️ 数字优惠券	列出、搜索并领取优惠券以省钱
🔄 自动刷新会话	自动处理机器人检测（约 15 秒）

---

📦 安装

快速开始

pip install texas-grocery-mcp

完整安装（推荐）🚀

pip install texas-grocery-mcp[browser]
playwright install chromium

通过嵌入式浏览器启用快速自动刷新（约 15 秒）。

前置条件

购物车操作和会话管理还需要 Playwright MCP：

npm install -g @anthropic-ai/mcp-playwright

---

⚙️ 配置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-playwright"]
    },
    "heb": {
      "command": "uvx",
      "args": ["texas-grocery-mcp"],
      "env": {
        "HEB_DEFAULT_STORE": "590"
      }
    }
  }
}

环境变量

变量	描述	默认值
HEB_DEFAULT_STORE	默认门店 ID	无
REDIS_URL	Redis 缓存 URL	无（内存中）
LOG_LEVEL	日志级别	INFO

---

🎯 使用示例

🏪 查找门店

User: Find HEB stores near Austin, TX

Agent uses: store_search(address="Austin, TX", radius_miles=10)

🔍 搜索商品

User: Search for organic milk

Agent uses: store_change(store_id="590")
Agent uses: product_search(query="organic milk")

📋 获取商品详情

User: What are the ingredients in H-E-B olive oil?

Agent uses: product_search(query="heb olive oil")
Agent uses: product_get(product_id="127074")
# Returns: ingredients, nutrition facts, warnings, dietary attributes

product_get 工具会返回：

• 🥗 配料 - 完整的配料声明
• 📊 营养成分 - 完整的 FDA 营养标签
• ⚠️ 安全警告 - 过敏原信息和注意事项
• 🌿 膳食属性 - 无麸质、有机、纯素、符合犹太教规等
• 📍 门店位置 - 货架或区域

🛒 添加到购物车

User: Add 2 gallons of milk to my cart

Agent uses: cart_add(product_id="123456", quantity=2)
# Returns preview for confirmation

Agent uses: cart_add(product_id="123456", quantity=2, confirm=true)
# ✅ Added to cart!

🎟️ 领取优惠券

User: Find coupons for cereal

Agent uses: coupon_search(query="cereal")
Agent uses: coupon_clip(coupon_id="ABC123", confirm=true)
# ✅ Coupon clipped!

---

🔐 会话管理

HEB 使用机器人检测，会话每约 11 分钟过期一次。此 MCP 会自动处理！

⚡ 快速自动刷新（推荐）

安装 [browser] 支持后：

Agent uses: session_refresh()
# ✅ Completes in ~10-15 seconds

🔑 自动登录

保存一次凭据，即可自动登录：

Agent uses: session_save_credentials(email="[email protected]", password="...")
# Credentials stored securely in system keyring
# Future session refreshes will auto-login!

---

🧰 可用工具

🏪 门店工具

工具	描述
store_search	按地址查找门店
store_change	设置首选门店
store_get_default	获取当前默认门店

🔍 商品工具

工具	描述
product_search	搜索商品及其价格
product_search_batch	搜索多个商品（最多 20 个）
product_get	获取商品详细信息

🛒 购物车工具

工具	描述
cart_check_auth	检查身份验证状态
cart_get	查看购物车内容
cart_add	添加商品（需要确认）
cart_add_many	批量添加多个商品
cart_remove	移除商品

🎟️ 优惠券工具

工具	描述
coupon_list	列出可用优惠券
coupon_search	按关键词搜索优惠券
coupon_clip	领取优惠券
coupon_clipped	列出已领取的优惠券

🔐 会话工具

工具	描述
session_status	检查会话状态
session_refresh	刷新／登录会话
session_save_credentials	保存凭据以便自动登录
session_clear	登出

---

📚 文档

• 🔧 故障排除指南 - 常见问题的解决方案
• 🤝 参与贡献 - 如何参与贡献
• 📝 更新日志 - 版本历史
• 🔒 安全 - 安全政策

---

🛠️ 开发

# Clone repository
git clone https://github.com/mgwalkerjr95/texas-grocery-mcp
cd texas-grocery-mcp

# Install with dev dependencies
pip install -e ".[dev]"
playwright install chromium

# Run tests
pytest tests/ -v

# Linting & type checking
ruff check src/
mypy src/

🐳 Docker

docker-compose up --build

---

🏗️ 架构

┌─────────────────────────────────────────────────────────────┐
│                    User's MCP Environment                    │
│                                                             │
│  ┌─────────────────────┐    ┌─────────────────────────────┐ │
│  │  🎭 Playwright MCP  │    │   🛒 Texas Grocery MCP      │ │
│  │  (Browser Auth)     │───▶│   (Grocery Logic)           │ │
│  └─────────────────────┘    └─────────────────────────────┘ │
│                                        │                     │
└────────────────────────────────────────┼─────────────────────┘
                                         │
                                         ▼
                                   🌐 HEB GraphQL API

---

📄 许可证

MIT © Michael Walker

---

由 ❤️ 于 Texas 🤠 制作