Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Texas Grocery MCP search for organic milk"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🤖 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.
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) |
Related MCP server: my-heb-proxy
pip install texas-grocery-mcppip install texas-grocery-mcp[browser]
playwright install chromiumThis enables fast auto-refresh (~15 seconds) using an embedded browser.
For cart operations and session management, you'll also need Playwright MCP:
npm install -g @anthropic-ai/mcp-playwrightAdd 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"
}
}
}
}Variable | Description | Default |
| Default store ID | None |
| Redis cache URL | None (in-memory) |
| Logging level | INFO |
User: Find HEB stores near Austin, TX
Agent uses: store_search(address="Austin, TX", radius_miles=10)User: Search for organic milk
Agent uses: store_change(store_id="590")
Agent uses: product_search(query="organic milk")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 attributesThe 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
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!User: Find coupons for cereal
Agent uses: coupon_search(query="cereal")
Agent uses: coupon_clip(coupon_id="ABC123", confirm=true)
# ✅ Coupon clipped!HEB uses bot detection that expires every ~11 minutes. This MCP handles it automatically!
With [browser] support installed:
Agent uses: session_refresh()
# ✅ Completes in ~10-15 secondsSave 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!Tool | Description |
| Find stores by address |
| Set preferred store |
| Get current default store |
Tool | Description |
| Search products with pricing |
| Search multiple products (up to 20) |
| Get detailed product info |
Tool | Description |
| Check authentication status |
| View cart contents |
| Add item (requires confirmation) |
| Bulk add multiple items |
| Remove item |
Tool | Description |
| List available coupons |
| Search coupons by keyword |
| Clip a coupon |
| List your clipped coupons |
Tool | Description |
| Check session health |
| Refresh/login session |
| Save credentials for auto-login |
| Logout |
🔧 Troubleshooting Guide - Solutions for common issues
🤝 Contributing - How to contribute
📝 Changelog - Version history
🔒 Security - Security policy
# 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-compose up --build┌─────────────────────────────────────────────────────────────┐
│ User's MCP Environment │
│ │
│ ┌─────────────────────┐ ┌─────────────────────────────┐ │
│ │ 🎭 Playwright MCP │ │ 🛒 Texas Grocery MCP │ │
│ │ (Browser Auth) │───▶│ (Grocery Logic) │ │
│ └─────────────────────┘ └─────────────────────────────┘ │
│ │ │
└────────────────────────────────────────┼─────────────────────┘
│
▼
🌐 HEB GraphQL APIMIT © Michael Walker
Add an item to the shopping cart with verification.
Without confirm=true, returns a preview of the action. With confirm=true, executes the action and VERIFIES it worked.
IMPORTANT: Use both product_id and sku_id from product_search results:
product_id: shorter ID (e.g., '127074')
sku_id: longer ID (e.g., '4122071073')
Returns error if item wasn't actually added to cart.
Inputs: product_id (required), sku_id, confirm, quantity. Returns: object
Add multiple items to cart with a single confirmation.
This is more efficient than calling cart_add multiple times and provides a single confirmation gate for the entire batch.
IMPORTANT: This operation uses STRICT success semantics. If ANY item fails to add, the entire operation is reported as a FAILURE. Items that were successfully added will remain in the cart, but you'll receive a clear list of which items failed.
Args: items: List of items, each with product_id, sku_id, and quantity confirm: Must be True to actually add items (human-in-the-loop safety)
Returns: On success: All items added with details On failure: List of failed items with reasons (successful items stay in cart)
Inputs: items (required), confirm. Returns: object
Add item to cart with automatic ID correction.
If the initial add fails due to ID format issues and auto_correct_ids=True, this will search for the product and retry with the correct IDs.
This is a more resilient version of cart_add that can recover from incorrect ID formats by looking up the product.
Inputs: product_id (required), sku_id, confirm, quantity, +1 more. Returns: object
Check if authenticated for cart operations.
Returns authentication status and instructions if not authenticated. Use this before attempting cart operations.
Inputs: no named parameters. Returns: object
Get current cart contents.
Returns all items in the cart with quantities and prices.
Inputs: no named parameters. Returns: object
Remove an item from the shopping cart.
Without confirm=true, returns a preview of the action. With confirm=true, executes the action.
Inputs: product_id (required), sku_id, confirm. Returns: object
Get available coupon categories/departments.
Returns a list of categories with the number of coupons in each. Use category names with coupon_list to filter coupons.
Inputs: no named parameters. Returns: object
Clip a coupon to your HEB account.
Without confirm=true, returns a preview of the action. With confirm=true, clips the coupon (requires authentication).
Clipped coupons automatically apply at checkout when you buy eligible items.
Inputs: coupon_id (required), confirm. Returns: object
List your clipped coupons.
Returns all coupons you've clipped to your HEB account. Clipped coupons automatically apply at checkout when you buy eligible items.
Inputs: limit. Returns: object
List available HEB digital coupons.
Returns coupons with discount details, descriptions, and expiration dates. Filter by category to find coupons in specific departments.
Inputs: limit, category. Returns: object
Search for HEB coupons by keyword.
Search for coupons by product name, brand, or discount type.
Inputs: query (required), limit. Returns: object
Liveness probe - is the process running?
Returns a simple alive status. Use for Kubernetes liveness probes.
Inputs: no named parameters. Returns: object
Readiness probe - can the server handle requests?
Returns detailed component health. Use for Kubernetes readiness probes.
Inputs: no named parameters. Returns: object
Get comprehensive details for a single product.
Returns detailed product information including:
Full description
Complete ingredients text
Safety/allergen warnings
Nutritional information (full FDA panel for packaged food)
Storage and preparation instructions
Dietary attributes (Gluten-Free, Organic, Vegan, etc.)
Store location (aisle or section)
Use this when you need more information than product_search provides, such as checking ingredients for dietary restrictions or allergens.
Args: product_id: The product ID from product_search results store_id: Optional store ID for store-specific pricing
Returns: Comprehensive product details or error response
Inputs: product_id (required), store_id. Returns: object
Search for products at an HEB store.
Returns products matching the query with pricing and availability for the specified store.
Inputs: query (required), limit, fields, store_id. Returns: object
Search for multiple products at once.
More efficient than calling product_search multiple times. Handles throttling internally to prevent rate limiting.
Returns results for each query, with availability at the specified store.
Inputs: queries (required), store_id, limit_per_query. Returns: object
Clear saved session cookies.
Use this to log out or clear invalid session data. After clearing, you will need to run session_refresh again.
Note: This does NOT clear saved credentials. Use session_clear_credentials() to remove stored login credentials.
Inputs: no named parameters. Returns: object
Remove stored HEB login credentials.
After clearing, session_refresh will fall back to manual browser login when your session expires.
Returns: dict with success status
Note: This does NOT clear your current session. Use session_clear() to remove session cookies.
Inputs: no named parameters. Returns: object
Refresh HEB session cookies and tokens.
Uses embedded browser when available (fast: ~10-15 seconds). If credentials are saved and login is required, attempts automatic login. Falls back to returning Playwright MCP commands if browser dependencies aren't installed.
Args: headless: Run browser without visible window (default True). Set to False if you need to complete a manual login (e.g., when your session has fully expired). timeout: Maximum time to wait for page load in milliseconds. Default 30000 (30 seconds). login_timeout: Maximum time to wait for manual login in milliseconds. Default 300000 (5 minutes). Only used when headless=False. use_saved_credentials: If True and credentials are stored, attempt automatic login when session is expired. Default True.
Returns: dict with one of these statuses: - {"status": "success", ...} - Login/refresh completed successfully - {"status": "human_action_required", "action": "login" | "captcha" | "2fa" | "waf", ...} Human intervention required (login form, CAPTCHA, 2FA, or a WAF/security interstitial). The browser remains open; complete the action, then call session_refresh() again. - {"status": "failed", ...} - Login/refresh failed with error details
Use this tool when:
session_status shows needs_refresh: true
session_status shows refresh_recommended: true
product_search returns security_challenge_detected: true
You want to proactively refresh before token expires
CAPTCHA/2FA handling:
When CAPTCHA or 2FA is detected, returns immediately with screenshot_path
The screenshot shows exactly what the user sees in the browser
Use the Read tool to view the screenshot and describe it to the user
The browser stays open - user solves CAPTCHA/enters code in that window
After solving, call session_refresh() again to continue the login flow
Repeat until status is "success" or "failed"
Inputs: timeout, headless, login_timeout, use_saved_credentials. Returns: object
Save HEB login credentials for automatic login.
Credentials are stored securely using:
OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)
Encrypted file fallback when keyring is unavailable
After saving, session_refresh will automatically use these credentials when your session expires, eliminating manual browser login.
Args: email: Your HEB.com account email address password: Your HEB.com account password
Returns: dict with success status and storage method used
Security notes:
Credentials are encrypted at rest
Password is never logged or exposed in output
Use session_clear_credentials() to remove stored credentials
Example: session_save_credentials("user@example.com", "mypassword") # Now session_refresh will auto-login when session expires
Inputs: email (required), password (required). Returns: object
Get instructions for saving browser session cookies.
Call this to get step-by-step instructions for authenticating via Playwright MCP and saving the session for fast API access.
For automatic session extraction, use session_refresh instead.
Inputs: no named parameters. Returns: object
Get current session status including token lifecycle and credential storage.
Returns comprehensive session information:
authenticated: Whether session is valid
needs_refresh: Whether refresh is required now (token expired)
refresh_recommended: Whether proactive refresh is advised (< 4 hours remaining)
time_remaining_hours: Hours until token expires
expires_at: ISO timestamp of expiration
message: Human-readable status
credentials_stored: Whether HEB credentials are saved for auto-login
Use this to check session health before operations or to decide when to proactively refresh.
Inputs: no named parameters. Returns: object
Change the active store for HEB operations.
When authenticated: Changes the store on HEB.com via their API with verification. When not authenticated: Sets a local default for product searches.
The store change is VERIFIED by checking the cart's actual store after the mutation. This ensures we never return success when the store didn't actually change (e.g., due to cart conflicts).
Args: store_id: The store ID to change to ignore_conflicts: If True, force store change even if cart has items unavailable at the new store or with price changes. Default False.
Inputs: store_id (required), ignore_conflicts. Returns: object
Get the currently set default store.
Returns the default store ID if set, otherwise indicates no default.
Inputs: no named parameters. Returns: object
Search for HEB stores near an address.
Returns stores sorted by distance, including store ID, name, address, and distance from the search location.
Inputs: address (required), radius_miles. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 25 tools
Each tool targets a distinct function: sessions, coupons, cart, products, stores, and health. Even within groups like cart_add variants, descriptions clarify differences. Overlaps are minimal.
Tool names mix verb_noun (store_search, product_get), noun_noun (coupon_categories), and adjective_noun (health_live). While readable, there is no consistent pattern across the set.
25 tools cover multiple domains (sessions, coupons, cart, products, stores, health) without feeling bloated. The count is at the higher end but still reasonable for the scope.
The tool surface covers core grocery operations: product discovery, store selection, coupon management, cart manipulation, and session handling. Missing checkout or order history, but pre-checkout coverage is solid.
Search live store shelves, verify delivery windows, and run instant AI agent checkouts.
Manage your NanoCart store from any AI agent: products, orders, coupons, subscribers, reports.
Live product discovery for AI shopping agents, with shopper-approved retailer handoff.
The E-commerce Marketplace For Every AI Agent. A Governed Catalog Of 600M+ US Products, Plus Four Agent Ready Capabilities Search, Price Comparison, Product-Vs-Product, And Detailed Q&A.
