🛒 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