appie-mcp
Use this MCP server to connect an AI assistant to Albert Heijn grocery data and account functions, with read access plus limited list/bonus writes and no checkout.
Check login/session status and retrieve member profile and Bonus card details.
Search products, get product details, alternatives, bulk product cards, search suggestions, predictive favorites, categories, and subcategories.
Browse weekly Bonus offers and personal Bonus Box offers, activate selected personal bonuses, and generate a promo digest from frequent purchases.
Read the primary shopping list and favorite lists; add/remove shopping-list items and check/uncheck favorite-list items.
Read the active online cart (read-only).
List digital receipts and get receipt line-item details.
Search Allerhande recipes and get recipe instructions/ingredients.
Search nearby stores and clearance bargains.
Inspect response-cache statistics for diagnostics.
No payment, credit-card, or automatic checkout actions.
Connects to Albert Heijn (Appie) supermarket services, providing tools for product search and details, weekly Bonus offers, personal Bonus Box activation, shopping lists and favorite lists, digital receipts, Allerhande recipes, store search, clearance bargains, and habit-based discount alerts. Checkout and payment remain human-controlled.
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., "@appie-mcp What Bonus deals are available at Albert Heijn this week?"
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.
appie-mcp
Model Context Protocol (MCP) server for Albert Heijn (Appie). Connects AI assistants (like Claude Desktop, Cursor, and Continue) directly to Albert Heijn’s supermarket services.
Features include product search, weekly Bonus offers, personal Bonus Box, Mijn Lijstjes (favorite lists) with item completion, digital receipts (kassabonnen), Allerhande recipes, and habit-based discount alerts.
⚡ Quick Start
1. Install Dependencies
npm install2. Log In
Run the interactive login command:
npm run loginSeamless Authentication: Automatically launches Google Chrome in stealth mode, opens Albert Heijn's sign-in page, intercepts the
appie://login-exitredirect, and saves the tokens totokens.json. No copy-pasting required!Headless / Manual Fallback: If you're on a headless server, run
npm run login -- --manualto paste the authorization redirect manually.
3. Check Status
npm run statusVerifies your live Albert Heijn connection, checks your Bonus card number, and confirms session validity.
4. Build
npm run buildRelated MCP server: Jumbo MCP Server
🛠️ MCP Tools (27 Tools)
1. Authentication & Member Profile
Tool | Type | Description |
| Read | Check session status and verify customer identity & Bonus card connection. |
| Read | Get customer loyalty profile, name, email, and 13-digit Bonus card number. |
2. Product Catalog & Search
Tool | Type | Description |
| Read | Search product catalog by keyword, with price sorting and bonus filters. |
| Read | Get detailed product info (pricing, nutrition, allergens, unit sizes). |
| Read | Find brand swaps, store-brand alternatives, or dietary substitutes. |
| Read | Fetch product cards in bulk for multiple product IDs (e.g. |
| Read | Get search query autocomplete keywords and suggestions. |
| Read | Fetch predictive favorite recommendations and frequently reordered products. |
3. Categories & Shelves
Tool | Type | Description |
| Read | Browse top-level supermarket shelves/categories. |
| Read | Fetch child subcategories for a given supermarket category ID. |
4. Promotions, Bonus Deals & Personal Bonus Box
Tool | Type | Description |
| Read | Browse active weekly Bonus folder promotions (1+1 gratis, 2e halve prijs). |
| Read | View the 5 personalized weekly Bonus Box offers for the member. |
| Write | Activate selected weekly Bonus Box promotions for a Bonus card number. |
| Read | Mines recent receipts to answer: "What that I frequently buy is on Bonus discount right now?" |
5. Shopping Lists & Favorites (Mijn Lijstjes)
Tool | Type | Description |
| Read | Retrieve the primary in-app shopping list items and notes. |
| Write | Add free-text items or products to the primary shopping list. |
| Write | Remove an item from the primary shopping list by ID. |
| Read | List saved custom lists (Mijn Lijstjes, e.g., 'Weekly Staples', 'Party'). |
| Write | Tick off items as collected in a favorite list ( |
6. Active Online Cart
Tool | Type | Description |
| Read | Read-only view of the user's active Albert Heijn online shopping cart and order summary. |
7. Digital Receipts (Kassabonnen)
Tool | Type | Description |
| Read | List in-store receipts (kassabonnen) with dates, store name, and totals. |
| Read | Inspect line items, unit prices, discounts, and payment methods for a receipt. |
8. Allerhande Recipes
Tool | Type | Description |
| Read | Search official Allerhande recipes by dish name or ingredient. |
| Read | Get step-by-step cooking instructions and mapped ingredient lists. |
9. Store Locator & Clearance
Tool | Type | Description |
| Read | Search nearby AH stores, facilities, and opening hours. |
| Read | Query store-specific clearance markdowns (vandaag-af / 35% discount items). |
10. Diagnostics
Tool | Type | Description |
| Read | Report the response cache: enabled state, hits, misses, hit rate, entries, evictions. |
🗄️ Caching & Data Freshness
Albert Heijn's API sends cache-control: no-store and no ETag, so nothing can
be cached at the HTTP layer. To cut request volume (and the load a bot-managed
edge puts on your account), this server keeps a process-local TTL cache in
front of its single HTTP choke point.
Scope: in memory only, for the lifetime of the running MCP server process. Nothing is written to disk, no cache survives a restart, and no cached response contains your tokens.
What is cached, and for how long
Data | TTL | Why |
Product detail ( | 24 hours | A product page is stable for a day |
Categories & sub-categories, stores, Allerhande recipes | 24 hours | Near-static reference data |
Product search results | 30 minutes | Offer prices churn daily |
Bonus folder, personal Bonus Box, clearance (vandaag-af), predictive favorites | 30 minutes | Weekly campaign, daily markdowns |
Receipt line items ( | 30 days | A closed receipt is immutable |
Everything else | — | See below |
What is never cached
Your member profile, the receipt overview list, your shopping list, your favorite lists, and the active online cart are always fetched live, never served from the cache. Those carry live personal state, and a stale read there would make the assistant re-add an item you just added.
What this means for you
Prices and offers can be up to 30 minutes old, and product pages up to 24 hours old. A price change during that window is not reflected. If you need the current shelf price, say so and the assistant can rely on a fresh search result for a different term, or you can restart the server to drop the cache.
Caching is per process, not per client. One cache instance serves every tool call in the server process, and an anonymous session reuses a single minted token instead of one per request. Only a client that spawns a new process per tool call loses the cache between calls — then every
ah_cache_statsreading is all zeros however many searches precede it.Kill switch: set
APPIE_MCP_CACHE=offto disable the cache entirely (for debugging, or if you need guaranteed-live data).APPIE_MCP_CACHE_MAX_ENTRIEScaps the number of cached responses (default 500).Verify it: call
ah_cache_statsfor the live hit/miss counters of the running server.npm run statusprints the cache configuration (enabled state and size cap) — it starts a separate process, so it cannot show the running server's counters.
⚙️ Configuration in Claude Desktop
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"appie": {
"command": "node",
"args": ["/Users/robert/Developer/appie-mcp/dist/index.js"]
}
}
}🔒 Safety & Guardrails
No Automatic Checkout: The server does not handle payment, credit cards, or final order submission. All purchases and checkout actions remain strictly human-in-the-loop.
Pluggable Token Storage: For headless or containerized environments, custom implementations of
TokenStore(FileTokenStore,MemoryTokenStore,HttpTokenStore, or custom backends) can be plugged in viasetTokenStore().
📄 License
MIT © Robert Schulze Dieckhoff
Available Tools
27 toolsah_activate_personal_bonusActivate Personal Bonus OffersB
Activate selected weekly Bonus Box promotions for a given Bonus card number.
Inputs: bonus_card_number (required), selected_bonus_ids (required).
ah_add_to_shopping_listAdd Items to Albert Heijn Shopping ListA
Add one or more free-text items or products to the user's Albert Heijn shopping list. WRITES to the real AH account.
Inputs: items (required).
ah_cache_statsGet Response Cache StatisticsARead-only
Report the in-process response cache: enabled state, hits, misses, hit rate, stored entries and evictions. Use to verify that cached Albert Heijn responses are reused instead of re-fetched.
Inputs: no named parameters.
ah_check_favorite_list_itemCheck / Uncheck Favorite List ItemB
Tick an item off as collected (checked=true) or un-tick it in a favorite list.
Inputs: item_id (required), list_id (required), checked.
ah_get_bonus_offersGet Albert Heijn Weekly Bonus OffersARead-only
Browse active national Bonus folder discounts, promotions (e.g. 1+1 gratis, 2e halve prijs), and validity windows. The folder is far larger than one page: walk page with limit to see more of it. Cached for up to 30 minutes.
Inputs: page, limit.
ah_get_cartGet Online CartARead-only
Read-only view of the user's active Albert Heijn online shopping cart and order summary. Always fetched live, never cached.
Inputs: no named parameters.
ah_get_categoriesGet Albert Heijn Product CategoriesARead-only
Get top-level supermarket product shelves and categories (e.g. Aardappel/groente/fruit, Bakkerij, Zuivel). Cached for up to 24 hours.
Inputs: no named parameters.
ah_get_clearance_bargainsGet Store Clearance Bargains (Overblijvers)ARead-only
Fetch today-only dynamic clearance markdowns (vandaag-af / 35% discount items) for a given store ID. Cached for up to 30 minutes.
Inputs: store_id (required).
ah_get_favorite_listsGet Albert Heijn Favorite Lists (Mijn Lijstjes)ARead-only
Get user's saved custom favorite lists (e.g. 'Weekly Staples', 'Party') with item counts.
Inputs: no named parameters.
ah_get_personal_bonusGet Personal Bonus Box OffersARead-only
Retrieve the 5 personalized weekly Bonus Box promotions for the logged-in Albert Heijn member. Cached for up to 30 minutes.
Inputs: no named parameters.
ah_get_predictive_favoritesGet Predictive FavoritesARead-only
Fetch predictive favorite recommendations and frequently reordered products predicted by Albert Heijn. Cached for up to 30 minutes.
Inputs: no named parameters.
ah_get_productGet Albert Heijn Product DetailsARead-only
Get detailed information for a specific Albert Heijn product: description, nutritional values, allergens, unit sizes, and pricing. Product pages are cached for up to 24 hours.
Inputs: product_id (required).
ah_get_product_alternativesGet Product Alternatives & SubstitutesARead-only
Find direct brand alternatives, store-brand swaps, or dietary substitutes for a product. Cached for up to 24 hours.
Inputs: product_id (required).
ah_get_products_bulkGet Products BulkARead-only
Fetch product details in bulk for multiple Albert Heijn product IDs (e.g. ['wi196825', 'wi187593']). Cached for up to 24 hours.
Inputs: product_ids (required).
ah_get_profileGet Albert Heijn Member ProfileARead-only
Get customer loyalty profile, name, email, and 13-digit Bonus card number.
Inputs: no named parameters.
ah_get_promo_digestGet Albert Heijn Promo DigestARead-only
Answer 'of the things I frequently buy, what is on Bonus discount right now?'. Mines receipts inside the requested window — paging back to the oldest receipt that falls in it, up to 150 — and cross-references them against active offers.
Inputs: days, limit, min_times.
ah_get_receipt_detailsGet Albert Heijn Receipt DetailsARead-only
Get detailed line items, unit prices, discounts, and total amount for a specific store receipt. A closed receipt is immutable, so it is cached for 30 days.
Inputs: transaction_id (required).
ah_get_recipe_detailsGet Allerhande Recipe Details & IngredientsARead-only
Get full cooking steps and structured ingredient list (with product mappings) for an Allerhande recipe. Cached for up to 24 hours.
Inputs: recipe_id (required).
ah_get_search_suggestionsGet Search SuggestionsARead-only
Get search autocompletion suggestions and related grocery query keywords from Albert Heijn. Cached for up to 30 minutes.
Inputs: query (required), limit.
ah_get_shopping_listGet Albert Heijn Shopping ListARead-only
Get the user's primary in-app shopping list ('Boodschappenlijst'): items, free-text notes, and checked states. Always fetched live, never cached.
Inputs: no named parameters.
ah_get_sub_categoriesGet SubcategoriesARead-only
Fetch child subcategories for a specific supermarket category ID. Cached for up to 24 hours.
Inputs: category_id (required).
ah_list_receiptsList Albert Heijn ReceiptsARead-only
List in-store cash register receipts (kassabonnen) with date, store name, and total. Pagination is real: page and size walk the whole history, and a size above 100 is fetched in 100-row windows. Always fetched live, never cached.
Inputs: page, size.
ah_loginCheck Albert Heijn Login StatusARead-only
Check authentication status or verify session with Albert Heijn. Returns member identity, Bonus card details, and connection status.
Inputs: no named parameters.
ah_remove_from_shopping_listRemove Item from Albert Heijn Shopping ListBDestructive
Remove an item from the primary shopping list by its item ID.
Inputs: item_id (required).
ah_search_productsSearch Albert Heijn ProductsARead-only
Search the Albert Heijn grocery catalog by keyword. Returns matching products with current prices, previous prices, active bonus discounts, unit prices, and web links. Results are cached for up to 30 minutes.
Inputs: query (required), page, sort, limit, +1 more.
ah_search_recipesSearch Allerhande RecipesARead-only
Search the official Albert Heijn Allerhande recipe collection by dish name, ingredient, or keyword. Cached for up to 24 hours.
Inputs: query (required), limit.
ah_search_storesSearch Albert Heijn StoresARead-only
Search nearby Albert Heijn stores by postal code or city name to check opening hours, distance, and facilities. Cached for up to 24 hours.
Inputs: query.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Most tools target an unambiguous resource+action pair (search_products vs get_product vs get_products_bulk, get_bonus_offers vs get_personal_bonus vs activate_personal_bonus). The main overlap is ah_login vs ah_get_profile, which both return member identity and Bonus card details, plus mild overlap between ah_get_search_suggestions and ah_search_products. ah_cache_stats is a developer/meta tool sitting among user-facing ones, but it is still clearly distinct.
All tools use a consistent ah_ prefix with snake_case and a verb_noun pattern (get_*, search_*, add_*, remove_*, activate_*, check_*, list_*). Minor deviations exist: ah_login is a bare verb and ah_cache_stats is noun-only without an action verb. Otherwise highly predictable.
27 tools is heavy and sits at the top of the scale, though the grocery domain is genuinely broad (catalog, categories, stores, bonus, receipts, lists, recipes, profile). Some tools feel like internal plumbing rather than agent primitives (ah_cache_stats, ah_get_promo_digest could arguably fold into bonus tools). Borderline heavy but not gratuitous.
Coverage is strong: read paths for products, categories, stores, recipes, receipts, bonus offers and lists, plus writes for shopping list and Bonus activation. The notable gap is the cart, which is read-only (ah_get_cart) with no add-to-cart or quantity update, and favorite lists cannot be created or edited beyond checking items. Agents can work around the cart gap by using the shopping list.
Maintenance
Related MCP Connectors
Persistent shopping memory for AI assistants. The AI reasons; Kaufliste stores and executes.
Search live store shelves, verify delivery windows, and run instant AI agent checkouts.
AI shopping assistant for the SuperCheap marketplace. Find and compare products and variants, manage your shopping cart, and request current delivery and checkout quotes. Connect with OAuth; availability depends on your market, and payment is completed on a hosted page.
Turn any shopping list into a ready-to-checkout grocery cart across 26 European supermarkets.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables shopping at Albert Heijn through an AI assistant by searching products, finding bonus deals and recipes, managing a shopping list and delivery order, and reading order history and receipts. It connects to the same API as the AH mobile app and handles login, token storage, and local stdio or remote HTTP transport.37444 npm1Apache 2.0
- AlicenseAqualityBmaintenanceEnables AI assistants to securely access a personal Dutch supermarket account, including digital receipts with itemized prices, discounts and VAT, loyalty points balance, and active shopping lists, plus search for nearby stores and products in the grocery catalog.20MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to search grocery products, manage shopping carts, and retrieve account, order, delivery, and discount information across multiple European online grocery platforms.MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to browse Albert Heijn Belgium without an account, offering seven read-only tools for product search, this week's bonus offers and bonus groups, product alternatives, and recipes. Everything runs anonymously over stdio or Streamable HTTP, with no login, shopping list, or ordering features.33Apache 2.0