🛒 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
Made with ❤️ in Texas 🤠
Metadata
Release files for texas-grocery-mcp 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| texas_grocery_mcp-0.1.3.tar.gz | 79.3 kB | Without provenance | Details for texas_grocery_mcp-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| texas_grocery_mcp-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for texas_grocery_mcp-0.1.3-py3-none-any.whl |
Total release size: 174.6 kB
Release files / texas_grocery_mcp-0.1.3.tar.gz
| Download URL | texas_grocery_mcp-0.1.3.tar.gz |
|---|---|
| Size | 79.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c68e480b08557d507ddfceb09ae599b570f06e754af1598c08531846f6073982
|
|
BLAKE2b-256 checksum How to use checksums |
db83fe500bbef1e244910df86dc55d0af920f7526159ae140d6779eb5ddbc4e4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / texas_grocery_mcp-0.1.3-py3-none-any.whl
| Download URL | texas_grocery_mcp-0.1.3-py3-none-any.whl |
|---|---|
| Size | 95.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0fb1820b3df018d5f82d2d427b952da51587fb6c93b280492afb48524416223c
|
|
BLAKE2b-256 checksum How to use checksums |
33d0a6ee2fe45e8a4b7fd76e749a71cc0ad775f182ebb538973ac0e68449c562
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for texas-grocery-mcp 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.