My H-E-B API Proxy & MCP Server

A lightweight TypeScript wrapper, HTTP proxy, and Model Context Protocol (MCP) server for the My H-E-B mobile app API. Built with Bun and Elysia.js.

I reverse-engineered the My H-E-B app's production GraphQL and REST APIs to extract their schema queries, headers, and API keys. This project wraps those endpoints into a clean, modern HTTP proxy and exposes them as standard MCP tools for LLMs.

For a detailed breakdown of the raw GraphQL queries, REST endpoints, headers, and parameters, see the API Specification.

[!WARNING]
This is an unofficial project built for educational and personal research purposes. It is not affiliated with, maintained by, or endorsed by H-E-B.

Intended Use

This project is designed to bridge the gap between large language models (LLMs) and real-time grocery data. By connecting your AI assistant (via MCP or the HTTP proxy), you can:

• Find the best deals: Ask your model to scan weekly ads or search for active coupons matching your shopping needs.
• Build smart shopping lists: Let the model suggest ingredients, compile organized grocery lists, and cross-reference them with actual store items and pricing.
• Locate nearby stores: Programmatically verify store locations, amenities, and operating hours.

---

Features

• Store Locator: Search H-E-B store details, distance, and operating hours by address or zip code.
• Digital Coupons: Search and filter H-E-B digital coupons by categories, print statuses, or search keywords.
• Product Catalog: Query the product catalog by store number and shopping context (curbside pickup, delivery, in-store) to fetch prices, SKU data, and images.
• Weekly Ads: Retrieve the weekly ad layout, promotional carousels, and direct publications flipbook links.
• Generic GraphQL Pass-through: Forward raw queries to H-E-B's edge API gateway while automatically injecting the correct interceptor headers.
• Model Context Protocol (MCP) Integration: Plug the API straight into your AI coding assistants or desktop clients as local tools.

---

How It Works

H-E-B's API gateway rejects requests without specific mobile app client headers. This server automatically injects:

1. API Key (apiKey): The extracted production key used by the Android app client.
2. User-Agent: Formatted to mimic a standard mobile device (e.g. MyHEB/2.80.1.1 (Android 14; Google Pixel 8)).
3. Request UUID (X-CLNT-REQ-UUID): Automatically generates a fresh random UUID for every request.

---

Tech Stack

• Runtime: Bun (fast JS/TS runtime)
• HTTP Server: Elysia.js (fast, type-friendly web framework)
• Documentation: Swagger UI (auto-generated at /swagger)
• Protocol: Model Context Protocol (MCP) TypeScript SDK

---

Getting Started

Prerequisites

Make sure you have Bun installed.

Installation

Clone the repository and install dependencies:

git clone https://github.com/ALLMarvelous/my-heb-proxy.git
cd my-heb-proxy
bun install

Running the HTTP Proxy

To run the server in development mode (with hot reloading):

bun run dev

The server will start at http://localhost:3000. You can open the interactive API docs in your browser at http://localhost:3000/swagger

---

API Endpoints

Method	Endpoint	Description
GET	/api/stores	Find stores near an address or zip code
POST	/api/coupons	Search and filter digital coupons
POST	/api/products	Search the product catalog for pricing/images
GET	/api/weekly-ad	Retrieve weekly ad component layouts
GET	/api/weekly-ad/flyer	Redirects to the static weekly ad flipbook PDF
POST	/api/graphql	Raw GraphQL proxy (auto-injects required headers)

---

MCP Server Integration

This project is a fully-compliant Model Context Protocol server. To use these tools in your AI workflow:

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-heb-mcp": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/my-heb-proxy/src/mcp-server.ts"]
    }
  }
}

Cursor / Windsurf

Add a new MCP server in your editor settings:

• Name: my-heb-mcp
• Type: command
• Command: bun run /absolute/path/to/my-heb-proxy/src/mcp-server.ts

Available MCP Tools

• search_stores (arguments: address, radiusMiles, includeNextAvailableTimeslot, includeEcommInactive)
• search_coupons (arguments: text, offset, limit, categories, couponTypes, sortOrder)
• search_products (arguments: query, storeId, shoppingContext)
• get_weekly_ad (arguments: storeId, shoppingContext)
• get_weekly_ad_flyer_url (arguments: storeId)