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.

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.

Related MCP server: Grocery Search MCP Server

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

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)