🛒 Texas Grocery MCP
🤖 Let AI do your grocery shopping! An MCP server that connects Claude to H-E-B grocery stores.
Search products, manage your cart, clip coupons, and more — all through natural conversation.
⚠️ This project is not affiliated with H-E-B. It uses unofficial web APIs and browser automation against HEB.com; use responsibly and ensure your usage complies with applicable terms and laws.
✨ Features
| Feature | Description |
|---|---|
| 🏪 Store Search | Find HEB stores by address or zip code |
| 🔍 Product Search | Search products with pricing and availability |
| 🛒 Cart Management | Add/remove items with human-in-the-loop confirmation |
| 📋 Product Details | Ingredients, nutrition facts, allergens, warnings |
| 🎟️ Digital Coupons | List, search, and clip coupons to save money |
| 🔄 Auto Session Refresh | Handles bot detection automatically (~15 seconds) |
📦 Installation
Quick Start
pip install texas-grocery-mcp
Full Installation (Recommended) 🚀
pip install texas-grocery-mcp[browser]
playwright install chromium
This enables fast auto-refresh (~15 seconds) using an embedded browser.
Prerequisites
For cart operations and session management, you'll also need Playwright MCP:
npm install -g @anthropic-ai/mcp-playwright
⚙️ Configuration
Claude Desktop
Add to ~/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"
}
}
}
}
Environment Variables
| Variable | Description | Default |
|---|---|---|
HEB_DEFAULT_STORE | Default store ID | None |
REDIS_URL | Redis cache URL | None (in-memory) |
LOG_LEVEL | Logging level | INFO |
🎯 Usage Examples
🏪 Finding a Store
User: Find HEB stores near Austin, TX
Agent uses: store_search(address="Austin, TX", radius_miles=10)
🔍 Searching Products
User: Search for organic milk
Agent uses: store_change(store_id="590")
Agent uses: product_search(query="organic milk")
📋 Getting Product Details
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
The product_get tool returns:
- 🥗 Ingredients - Full ingredient statement
- 📊 Nutrition Facts - Complete FDA panel
- ⚠️ Safety Warnings - Allergen info and precautions
- 🌿 Dietary Attributes - Gluten-free, organic, vegan, kosher, etc.
- 📍 Store Location - Aisle or section
🛒 Adding to Cart
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!
🎟️ Clipping Coupons
User: Find coupons for cereal
Agent uses: coupon_search(query="cereal")
Agent uses: coupon_clip(coupon_id="ABC123", confirm=true)
# ✅ Coupon clipped!
🔐 Session Management
HEB uses bot detection that expires every ~11 minutes. This MCP handles it automatically!
⚡ Fast Auto-Refresh (Recommended)
With [browser] support installed:
Agent uses: session_refresh()
# ✅ Completes in ~10-15 seconds
🔑 Auto-Login
Save your credentials once for automatic login:
Agent uses: session_save_credentials(email="you@email.com", password="...")
# Credentials stored securely in system keyring
# Future session refreshes will auto-login!
🧰 Available Tools
🏪 Store Tools
| Tool | Description |
|---|---|
store_search | Find stores by address |
store_change | Set preferred store |
store_get_default | Get current default store |
🔍 Product Tools
| Tool | Description |
|---|---|
product_search | Search products with pricing |
product_search_batch | Search multiple products (up to 20) |
product_get | Get detailed product info |
🛒 Cart Tools
| Tool | Description |
|---|---|
cart_check_auth | Check authentication status |
cart_get | View cart contents |
cart_add | Add item (requires confirmation) |
cart_add_many | Bulk add multiple items |
cart_remove | Remove item |
🎟️ Coupon Tools
| Tool | Description |
|---|---|
coupon_list | List available coupons |
coupon_search | Search coupons by keyword |
coupon_clip | Clip a coupon |
coupon_clipped | List your clipped coupons |
🔐 Session Tools
| Tool | Description |
|---|---|
session_status | Check session health |
session_refresh | Refresh/login session |
session_save_credentials | Save credentials for auto-login |
session_clear | Logout |
📚 Documentation
- 🔧 Troubleshooting Guide - Solutions for common issues
- 🤝 Contributing - How to contribute
- 📝 Changelog - Version history
- 🔒 Security - Security policy
🛠️ Development
# 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
🏗️ Architecture
┌─────────────────────────────────────────────────────────────┐
│ User's MCP Environment │
│ │
│ ┌─────────────────────┐ ┌─────────────────────────────┐ │
│ │ 🎭 Playwright MCP │ │ 🛒 Texas Grocery MCP │ │
│ │ (Browser Auth) │───▶│ (Grocery Logic) │ │
│ └─────────────────────┘ └─────────────────────────────┘ │
│ │ │
└────────────────────────────────────────┼─────────────────────┘
│
▼
🌐 HEB GraphQL API
📄 License
MIT © Michael Walker
<p align="center"> Made with ❤️ in Texas 🤠 </p>