MT 
mgwalkerjr95/texas-grocery-mcp
Developer tools47ย stars 0 forks Quality 55 Trend 55
๐ค Let AI do your grocery shopping! An MCP server that connects Claude to H-E-B grocery stores.
Overview
๐ค Let AI do your grocery shopping! An MCP server that connects Claude to H-E-B grocery stores.
README
๐ 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="[email protected]", 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 ๐ค
Install
npx @anthropic-ai/mcp-playwrightConfiguration
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@anthropic-ai/mcp-playwright"]
},
"heb": {
"command": "uvx",
"args": ["texas-grocery-mcp"],
"env": {
"HEB_DEFAULT_STORE": "590"
}
}
}
}