🛒 Texas Grocery MCP

PyPI version License: MIT

🤖 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

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