Skip to main content
Glama

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 install

2. Log In

Run the interactive login command:

npm run login
  • Seamless Authentication: Automatically launches Google Chrome in stealth mode, opens Albert Heijn's sign-in page, intercepts the appie://login-exit redirect, and saves the tokens to tokens.json. No copy-pasting required!

  • Headless / Manual Fallback: If you're on a headless server, run npm run login -- --manual to paste the authorization redirect manually.

3. Check Status

npm run status

Verifies your live Albert Heijn connection, checks your Bonus card number, and confirms session validity.

4. Build

npm run build

Related MCP server: Jumbo MCP Server

🛠️ MCP Tools (27 Tools)

1. Authentication & Member Profile

Tool

Type

Description

ah_login

Read

Check session status and verify customer identity & Bonus card connection.

ah_get_profile

Read

Get customer loyalty profile, name, email, and 13-digit Bonus card number.

Tool

Type

Description

ah_search_products

Read

Search product catalog by keyword, with price sorting and bonus filters.

ah_get_product

Read

Get detailed product info (pricing, nutrition, allergens, unit sizes).

ah_get_product_alternatives

Read

Find brand swaps, store-brand alternatives, or dietary substitutes.

ah_get_products_bulk

Read

Fetch product cards in bulk for multiple product IDs (e.g. ['wi196825', 'wi187593']).

ah_get_search_suggestions

Read

Get search query autocomplete keywords and suggestions.

ah_get_predictive_favorites

Read

Fetch predictive favorite recommendations and frequently reordered products.

3. Categories & Shelves

Tool

Type

Description

ah_get_categories

Read

Browse top-level supermarket shelves/categories.

ah_get_sub_categories

Read

Fetch child subcategories for a given supermarket category ID.

4. Promotions, Bonus Deals & Personal Bonus Box

Tool

Type

Description

ah_get_bonus_offers

Read

Browse active weekly Bonus folder promotions (1+1 gratis, 2e halve prijs).

ah_get_personal_bonus

Read

View the 5 personalized weekly Bonus Box offers for the member.

ah_activate_personal_bonus

Write

Activate selected weekly Bonus Box promotions for a Bonus card number.

ah_get_promo_digest

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

ah_get_shopping_list

Read

Retrieve the primary in-app shopping list items and notes.

ah_add_to_shopping_list

Write

Add free-text items or products to the primary shopping list.

ah_remove_from_shopping_list

Write

Remove an item from the primary shopping list by ID.

ah_get_favorite_lists

Read

List saved custom lists (Mijn Lijstjes, e.g., 'Weekly Staples', 'Party').

ah_check_favorite_list_item

Write

Tick off items as collected in a favorite list (checked: true/false).

6. Active Online Cart

Tool

Type

Description

ah_get_cart

Read

Read-only view of the user's active Albert Heijn online shopping cart and order summary.

7. Digital Receipts (Kassabonnen)

Tool

Type

Description

ah_list_receipts

Read

List in-store receipts (kassabonnen) with dates, store name, and totals. page/size walk the full history; a size above 100 is fetched in 100-row windows.

ah_get_receipt_details

Read

Inspect line items, unit prices, discounts, and payment methods for a receipt.

8. Allerhande Recipes

Tool

Type

Description

ah_search_recipes

Read

Search official Allerhande recipes by dish name or ingredient.

ah_get_recipe_details

Read

Get step-by-step cooking instructions and mapped ingredient lists.

9. Store Locator & Clearance

Tool

Type

Description

ah_search_stores

Read

Search nearby AH stores, facilities, and opening hours.

ah_get_clearance_bargains

Read

Query store-specific clearance markdowns (vandaag-af / 35% discount items).

10. Diagnostics

Tool

Type

Description

ah_cache_stats

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 (ah_get_product, ah_get_product_alternatives, ah_get_products_bulk)

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 (ah_get_receipt_details)

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_stats reading is all zeros however many searches precede it.

  • Kill switch: set APPIE_MCP_CACHE=off to disable the cache entirely (for debugging, or if you need guaranteed-live data). APPIE_MCP_CACHE_MAX_ENTRIES caps the number of cached responses (default 500).

  • Verify it: call ah_cache_stats for the live hit/miss counters of the running server. npm run status prints 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 via setTokenStore().

📄 License

MIT © Robert Schulze Dieckhoff

Available Tools

27 tools
ah_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 StatisticsA
Read-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 OffersA
Read-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 CartA
Read-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 CategoriesA
Read-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)A
Read-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)A
Read-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 OffersA
Read-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 FavoritesA
Read-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 DetailsA
Read-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 & SubstitutesA
Read-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 BulkA
Read-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 ProfileA
Read-only

Get customer loyalty profile, name, email, and 13-digit Bonus card number.

Inputs: no named parameters.

ah_get_promo_digestGet Albert Heijn Promo DigestA
Read-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 DetailsA
Read-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 & IngredientsA
Read-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 SuggestionsA
Read-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 ListA
Read-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 SubcategoriesA
Read-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 ReceiptsA
Read-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 StatusA
Read-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 ListB
Destructive

Remove an item from the primary shopping list by its item ID.

Inputs: item_id (required).

ah_search_productsSearch Albert Heijn ProductsA
Read-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 RecipesA
Read-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 StoresA
Read-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

    A3.7/5.0

    Scored across 27 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      37
      444 npm
      1
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      20
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search grocery products, manage shopping carts, and retrieve account, order, delivery, and discount information across multiple European online grocery platforms.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      33
      Apache 2.0