wegmans-mcp
An MCP (Model Context Protocol) server that lets AI assistants interact with Wegmans grocery stores. Search products, find store locations, manage your shopping cart, and access your purchase history — all through natural language.
What it does
This server connects to Wegmans' Algolia search API and commerce backend to expose 12 tools:
*Reads from local data synced by sync_purchase_history.
The unauthenticated tools work out of the box — no account needed. Cart and sync operations require your Wegmans credentials.
Setup
git clone https://github.com/BrianVia/wegmans-mcp.git
cd wegmans-mcp
npm install
npm run build
Add to Claude Code
{
"mcpServers": {
"wegmans": {
"command": "node",
"args": ["/path/to/wegmans-mcp/dist/index.js"],
"env": {
"WEGMANS_STORE": "133"
}
}
}
}
Add to Claude Desktop
{
"mcpServers": {
"wegmans": {
"command": "node",
"args": ["/path/to/wegmans-mcp/dist/index.js"],
"env": {
"WEGMANS_STORE": "133",
"WEGMANS_EMAIL": "[email protected]",
"WEGMANS_PASSWORD": "your-password",
"WEGMANS_CUSTOMER_ID": "your-customer-uuid"
}
}
}
}
Environment variables
Finding your store number
Every Wegmans has a numeric store ID used for pricing, inventory, and aisle locations.
Common stores:
Use the find_stores tool to look up others, or:
> find_stores("Reston")
Reston, VA — Store #146 — 11950 Hopper St., Reston, VA 20191
> find_stores("VA")
Dulles #7, Fairfax #16, Chantilly #133, Reston #146, Tysons #115, ...
The store number determines which products are available, what prices you see, and which aisle locations are returned. Stores carry different inventory, so this matters.
Finding your customer ID
Your customer ID is a UUID that Wegmans assigns to your account. To find it:
- Log into wegmans.com
- Open DevTools (F12) → Network tab
- Search for any request to
algolia.net - Look for
userTokenin the request body — that's your customer ID
It looks like: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (a UUID)
Usage examples
Search for products
Search returns product names, in-store and delivery prices, aisle locations, images, ratings, allergen info, and more.
> search_products("lactose free 2% milk")
1. fairlife 2% Reduced Fat Ultra-Filtered Milk, Lactose Free — $5.49 (Aisle: Dairy)
2. Lactaid Milk, Reduced Fat, 2% Milkfat — $5.99 (Aisle: Dairy)
3. Wegmans 2% Reduced Fat Lactose Free Milk — $3.79 (Aisle: Dairy)
4. Organic Valley Milk, Lactose Free, Reduced Fat, 2% — $6.29 (Aisle: Dairy)
> search_products("bananas", { max_results: 2 })
1. Bananas, Sold by the Each — $0.19 ($0.49/lb.) — Aisle: Produce
2. Organic Bananas, Bunch — $1.38 ($0.69/lb.) — Aisle: Produce
Add items to your cart
The add_to_cart tool takes a product ID (from search results) and quantity. It looks up the full product details, authenticates with Wegmans, and adds it to your real cart.
> add_to_cart("92685", 5)
Added to cart: 5x Bananas, Sold by the Each ($0.19 each)
> add_to_cart("116893", 1)
Added to cart: 1x Lactaid Milk, Reduced Fat, 2% Milkfat ($5.99 each)
Items accumulate — each add reads the existing cart first and merges the new item in, so you won't lose what's already there.
View your most-purchased items
The get_my_items tool returns your purchase history ranked by frequency. This is great for building a weekly shopping list or letting an AI suggest what you might need.
> get_my_items({ limit: 10 })
Your top 10 most-purchased items (out of 546 total):
1. Wegmans Grade AA Large Eggs, 18 Count — $2.49 (Aisle: Dairy)
2. Lactaid Milk, Reduced Fat, 2% Milkfat — $5.99 (Aisle: Dairy)
3. Bananas, Sold by the Each — $0.19 (Aisle: Produce)
4. Large Fresh Limes — $0.50 (Aisle: Produce)
5. Strawberries — $2.99 (Aisle: Produce)
6. Wegmans Organic Lemonade — $3.49 (Aisle: 18A)
7. Wegmans Cherry Tomatoes on the Vine, Flavor Bombs — $5.79 (Aisle: Produce)
8. Wegmans Pancake Mix — $2.29 (Aisle: 11B)
9. Lemons — $0.69 (Aisle: Produce)
10. MadeGood Mornings Soft Baked Blueberry Flavor Oat Bars — $4.49 (Aisle: 04B)
Bulk add your regular items
An AI assistant can combine get_my_items with add_to_cart to quickly build your weekly cart:
"Add my regular top 10 shopping items"
OK — Wegmans Grade AA Large Eggs, 18 Count (10 items in cart)
OK — Lactaid Milk, Reduced Fat, 2% Milkfat (10 items in cart)
OK — Bananas, Sold by the Each (10 items in cart)
OK — Large Fresh Limes (10 items in cart)
OK — Strawberries (10 items in cart)
...
Purchase intelligence — "What do I need this week?"
The real power: sync your full purchase history, then let the AI figure out what you need.
Step 1: Sync your history (fetches 63+ receipts and 71+ orders from Wegmans)
> sync_purchase_history
Purchase history synced:
- 63 in-store receipts (862 line items)
- 71 online orders (1238 line items)
- 2100 total purchase events
- 818 unique products tracked
Step 2: See your patterns
> get_purchase_patterns({ product_name: "milk" })
1. [~] Milk, Reduced Fat, 2% Milkfat (Dairy)
53 purchases | Every ~7 days | Last: 1d ago | Due in 6d
> get_purchase_patterns({ urgency: "overdue" })
1. [!!] Clementines, Bagged (Produce) — 68d ago, usually every 26d (42d overdue)
2. [!!] Whipped Cream Cheese Spread (Dairy) — 63d ago, usually every 24d (39d overdue)
...
Step 3: Get a smart shopping list
> get_shopping_suggestions({ lookahead_days: 7 })
1. [!!] Clementines, Bagged (Produce) [ID: 44091]
Last bought 68 days ago, you usually buy every 26 days (42 days overdue)
2. [!!] Cream Cheese Icing Cinnamon Rolls (Dairy) [ID: 139106]
Last bought 38 days ago, you usually buy every 24 days (15 days overdue)
3. [!] Bananas, Sold by the Each (Produce) [ID: 92685]
Last bought 5 days ago, you usually buy every 8 days (due in 3 days)
Step 4: Dive into a specific product
> get_product_history({ product_id: "116893" })
## Milk, Reduced Fat, 2% Milkfat (ID: 116893)
You buy this roughly every 7 days (based on 53 purchases). Last bought 1 day ago.
Summary: 53 purchases | Total spent: $351.49 | Avg per trip: $6.63
| Date | Qty | Price | Source | Store |
|------------|-----|--------|---------|-------|
| 2026-04-04 | 2 | $13.78 | order | - |
| 2026-03-26 | 1 | $6.89 | order | - |
| 2026-03-21 | 1 | $6.89 | order | - |
| ... | | | | |
The killer combo: Ask an AI assistant "add everything I need this week to my cart" — it calls get_shopping_suggestions then add_to_cart for each item.
Legacy: Refresh my-items from browser
The refresh_my_items tool still works for updating the Algolia-based frequency ranking. For full purchase history with timestamps and patterns, use sync_purchase_history instead.
Architecture
src/
index.ts # MCP server — tool definitions and handlers
algolia.ts # Algolia product search client
auth.ts # Azure AD B2C OAuth authentication (PKCE flow)
cart.ts # Cart operations (add to cart, get cart, product lookup)
stores.ts # Store locator (fetches from wegmans.com/api/stores)
receipts.ts # In-store receipt fetcher (63+ receipts with item detail)
orders.ts # Online order fetcher (71+ orders with line items)
my-items-api.ts # Wegmans My Items API (ranked list with lastPurchasedDate)
purchase-history.ts # Unified data layer — merges all sources, persists locally
patterns.ts # Pure analysis — intervals, predictions, shopping suggestions
my-items.ts # Query Algolia for scored product lists
refresh-my-items.ts # Parse and save purchase history data
data/
purchase-history.json # Unified purchase timeline (gitignored)
my-items.json # Legacy Algolia-based frequency cache (gitignored)
docs/
api-reference.md # Documented Wegmans API endpoints
How it works
Product search hits Wegmans' Algolia index directly using their public search API key. No authentication needed. Every product has store-specific pricing, aisle locations, and availability — so the WEGMANS_STORE setting matters.
Cart operations use Wegmans' commerce API at api.digitaldevelopment.wegmans.cloud. Authentication goes through Azure AD B2C with a PKCE OAuth flow — the server handles the full login flow (GET authorize page → POST credentials → GET auth code → exchange for token) and caches the access token until it expires.
Purchase intelligence syncs three API sources:
/commerce/receipts— 63+ in-store receipts with item-level detail (product, quantity, price, timestamp, store)/commerce/order/orders/{id}— 71+ online orders with line items/commerce/my-items— ranked product list withlastPurchasedDate
These are merged into a unified timeline in data/purchase-history.json. The patterns.ts module computes per-product purchase intervals using median (robust against outliers), classifies urgency, and generates shopping suggestions. Items you stopped buying are automatically filtered out.
Store-aware data
All product data is store-specific. The same product can have different prices, aisle locations, and availability across stores:
- Store 133 (Chantilly, VA): Bananas at $0.49/lb, Aisle: Produce
- Store 146 (Reston, VA): Same product, potentially different aisle position
The WEGMANS_STORE env var (or the store_number parameter on each tool) controls which store's data you see.
API details
See docs/api-reference.md for full documentation of the Wegmans APIs this server uses, including:
- Algolia product search (public, no auth)
- Store locator API (public, no auth)
- Cart management API (authenticated)
- Azure AD B2C authentication flow
Rate limits
From Wegmans' response headers:
- Product search (Algolia): 50,000 calls per period
- Cart API: 5,000 calls per period
Limitations
- No coupon management — The Algolia data includes digital coupon IDs, and the receipts show discount amounts, but clipping/applying coupons is not yet implemented.
- Single fulfillment type per cart — The cart API ties each cart to one fulfillment type (instore, pickup, or delivery).
- Pattern accuracy depends on data — Products with fewer than 3 purchases don't get interval predictions. Items you stopped buying are filtered out after 3x their usual interval or 90 days, whichever comes first.
- Sync is explicit — You must call
sync_purchase_historyto fetch fresh data. There is no background polling.
Prior art
This project was informed by the wegmans-shopping project, which uses Playwright to scrape product data via Algolia interception. This MCP server takes a different approach — hitting Algolia directly without a browser for search, and using the commerce API for cart operations.
License
ISC