{
  "markdown": "# 🛒 Texas Grocery MCP\n\n[![PyPI version](https://badge.fury.io/py/texas-grocery-mcp.svg)](https://pypi.org/project/texas-grocery-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/mgwalkerjr95/texas-grocery-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mgwalkerjr95/texas-grocery-mcp/actions/workflows/ci.yml)\n\n> 🤖 Let AI do your grocery shopping! An MCP server that connects Claude to H-E-B grocery stores.\n\n**Search products, manage your cart, clip coupons, and more — all through natural conversation.**\n\n⚠️ 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.\n\n---\n\n## ✨ Features\n\n| Feature | Description |\n|---------|-------------|\n| 🏪 **Store Search** | Find HEB stores by address or zip code |\n| 🔍 **Product Search** | Search products with pricing and availability |\n| 🛒 **Cart Management** | Add/remove items with human-in-the-loop confirmation |\n| 📋 **Product Details** | Ingredients, nutrition facts, allergens, warnings |\n| 🎟️ **Digital Coupons** | List, search, and clip coupons to save money |\n| 🔄 **Auto Session Refresh** | Handles bot detection automatically (~15 seconds) |\n\n---\n\n## 📦 Installation\n\n### Quick Start\n\n```bash\npip install texas-grocery-mcp\n```\n\n### Full Installation (Recommended) 🚀\n\n```bash\npip install texas-grocery-mcp[browser]\nplaywright install chromium\n```\n\nThis enables **fast auto-refresh** (~15 seconds) using an embedded browser.\n\n### Prerequisites\n\nFor cart operations and session management, you'll also need **Playwright MCP**:\n\n```bash\nnpm install -g @anthropic-ai/mcp-playwright\n```\n\n---\n\n## ⚙️ Configuration\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\"@anthropic-ai/mcp-playwright\"]\n    },\n    \"heb\": {\n      \"command\": \"uvx\",\n      \"args\": [\"texas-grocery-mcp\"],\n      \"env\": {\n        \"HEB_DEFAULT_STORE\": \"590\"\n      }\n    }\n  }\n}\n```\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `HEB_DEFAULT_STORE` | Default store ID | None |\n| `REDIS_URL` | Redis cache URL | None (in-memory) |\n| `LOG_LEVEL` | Logging level | INFO |\n\n---\n\n## 🎯 Usage Examples\n\n### 🏪 Finding a Store\n\n```\nUser: Find HEB stores near Austin, TX\n\nAgent uses: store_search(address=\"Austin, TX\", radius_miles=10)\n```\n\n### 🔍 Searching Products\n\n```\nUser: Search for organic milk\n\nAgent uses: store_change(store_id=\"590\")\nAgent uses: product_search(query=\"organic milk\")\n```\n\n### 📋 Getting Product Details\n\n```\nUser: What are the ingredients in H-E-B olive oil?\n\nAgent uses: product_search(query=\"heb olive oil\")\nAgent uses: product_get(product_id=\"127074\")\n# Returns: ingredients, nutrition facts, warnings, dietary attributes\n```\n\nThe `product_get` tool returns:\n- 🥗 **Ingredients** - Full ingredient statement\n- 📊 **Nutrition Facts** - Complete FDA panel\n- ⚠️ **Safety Warnings** - Allergen info and precautions\n- 🌿 **Dietary Attributes** - Gluten-free, organic, vegan, kosher, etc.\n- 📍 **Store Location** - Aisle or section\n\n### 🛒 Adding to Cart\n\n```\nUser: Add 2 gallons of milk to my cart\n\nAgent uses: cart_add(product_id=\"123456\", quantity=2)\n# Returns preview for confirmation\n\nAgent uses: cart_add(product_id=\"123456\", quantity=2, confirm=true)\n# ✅ Added to cart!\n```\n\n### 🎟️ Clipping Coupons\n\n```\nUser: Find coupons for cereal\n\nAgent uses: coupon_search(query=\"cereal\")\nAgent uses: coupon_clip(coupon_id=\"ABC123\", confirm=true)\n# ✅ Coupon clipped!\n```\n\n---\n\n## 🔐 Session Management\n\nHEB uses bot detection that expires every ~11 minutes. This MCP handles it automatically!\n\n### ⚡ Fast Auto-Refresh (Recommended)\n\nWith `[browser]` support installed:\n\n```\nAgent uses: session_refresh()\n# ✅ Completes in ~10-15 seconds\n```\n\n### 🔑 Auto-Login\n\nSave your credentials once for automatic login:\n\n```\nAgent uses: session_save_credentials(email=\"you@email.com\", password=\"...\")\n# Credentials stored securely in system keyring\n# Future session refreshes will auto-login!\n```\n\n---\n\n## 🧰 Available Tools\n\n### 🏪 Store Tools\n| Tool | Description |\n|------|-------------|\n| `store_search` | Find stores by address |\n| `store_change` | Set preferred store |\n| `store_get_default` | Get current default store |\n\n### 🔍 Product Tools\n| Tool | Description |\n|------|-------------|\n| `product_search` | Search products with pricing |\n| `product_search_batch` | Search multiple products (up to 20) |\n| `product_get` | Get detailed product info |\n\n### 🛒 Cart Tools\n| Tool | Description |\n|------|-------------|\n| `cart_check_auth` | Check authentication status |\n| `cart_get` | View cart contents |\n| `cart_add` | Add item (requires confirmation) |\n| `cart_add_many` | Bulk add multiple items |\n| `cart_remove` | Remove item |\n\n### 🎟️ Coupon Tools\n| Tool | Description |\n|------|-------------|\n| `coupon_list` | List available coupons |\n| `coupon_search` | Search coupons by keyword |\n| `coupon_clip` | Clip a coupon |\n| `coupon_clipped` | List your clipped coupons |\n\n### 🔐 Session Tools\n| Tool | Description |\n|------|-------------|\n| `session_status` | Check session health |\n| `session_refresh` | Refresh/login session |\n| `session_save_credentials` | Save credentials for auto-login |\n| `session_clear` | Logout |\n\n---\n\n## 📚 Documentation\n\n- 🔧 [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Solutions for common issues\n- 🤝 [Contributing](CONTRIBUTING.md) - How to contribute\n- 📝 [Changelog](CHANGELOG.md) - Version history\n- 🔒 [Security](SECURITY.md) - Security policy\n\n---\n\n## 🛠️ Development\n\n```bash\n# Clone repository\ngit clone https://github.com/mgwalkerjr95/texas-grocery-mcp\ncd texas-grocery-mcp\n\n# Install with dev dependencies\npip install -e \".[dev]\"\nplaywright install chromium\n\n# Run tests\npytest tests/ -v\n\n# Linting & type checking\nruff check src/\nmypy src/\n```\n\n### 🐳 Docker\n\n```bash\ndocker-compose up --build\n```\n\n---\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    User's MCP Environment                    │\n│                                                             │\n│  ┌─────────────────────┐    ┌─────────────────────────────┐ │\n│  │  🎭 Playwright MCP  │    │   🛒 Texas Grocery MCP      │ │\n│  │  (Browser Auth)     │───▶│   (Grocery Logic)           │ │\n│  └─────────────────────┘    └─────────────────────────────┘ │\n│                                        │                     │\n└────────────────────────────────────────┼─────────────────────┘\n                                         │\n                                         ▼\n                                   🌐 HEB GraphQL API\n```\n\n---\n\n## 📄 License\n\nMIT © Michael Walker\n\n---\n\n<p align=\"center\">\n  Made with ❤️ in Texas 🤠\n</p>\n",
  "bytes": 6962,
  "sha": "8bf21bac0a331d2bc8f2d1f86c7c5d58d4c2be82725c7dcc528d73225a7bdfad",
  "repo_slug": "mgwalkerjr95/texas-grocery-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mgwalkerjr95_texas_grocery_654c77ca/readme"
}