Texas Grocery

🛒 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

---

📦 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

---

🎯 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

🔍 Product Tools

🛒 Cart Tools

🎟️ Coupon Tools

🔐 Session Tools

---

📚 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

---

Made with ❤️ in Texas 🤠