albert-heijn-be-mcp
An unofficial MCP server for Albert Heijn (ah.be, no login needed in anonymous mode) that lets an AI assistant search products, bonus deals, recipes and — with a logged-in account — manage shopping lists, orders and receipts.
Search products (
ah_search_products): one or more queries at once, filter by bonus, diets/allergens (organic, vegan, gluten_free…), sort by price or Nutri-Score, optional images.Get product details (
ah_get_products): prices and deal fields, brand, category, Nutri-Score, optional nutrition, ingredients/allergens, description, images; plus alternatives/substitutes (ah_get_product_alternatives).Bonus offers (
ah_get_bonus_offers): this week's or next week's offers, keyword filter, categories, non-food toggle, "previously bought", and drill into group deals like "2+1 gratis" (ah_get_bonus_group_products).Recipes (
ah_search_recipes,ah_get_recipe): Allerhande recipes with ingredients, steps, nutrition, scaled servings; optionally add all ingredients to the shopping list in one step (ah_add_recipe_to_shopping_list).Stores & clearance (
ah_search_stores,ah_get_last_chance_items): nearby stores and today's vandaag-af markdowns.Shopping list (
ah_get_shopping_list,ah_add_to_shopping_list,ah_add_free_text_to_shopping_list,ah_remove_from_shopping_list,ah_clear_shopping_list).Favourite lists (
ah_get_favorite_lists,ah_create_favorite_list,ah_add_to_favorite_list,ah_remove_from_favorite_list,ah_delete_favorite_list).Delivery order (
ah_get_delivery_slots,ah_get_cart,ah_update_cart_item,ah_remove_from_cart,ah_clear_cart) — note slots can't be booked via the API.Orders & receipts (
ah_get_orders,ah_get_order_details,ah_get_frequent_items,ah_get_receipts,ah_get_receipt_details).Account (
ah_login,ah_logout,ah_get_member_profile) — irrelevant in--anonymousmode, which exposes only the seven read-only tools (products, bonus, bonus groups, alternatives, recipes) and needs no account or token.
Provides read-only access to Albert Heijn Belgium product and grocery data, including product search, this week's bonus offers and bonus groups, product alternatives, and recipes. No account or login is required in anonymous mode.
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., "@albert-heijn-be-mcp Find organic gluten-free pasta and show me any bonus deals on it"
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.
albert-heijn-be-mcp
Unofficial. Not affiliated with Albert Heijn or Ahold Delhaize. Based on olekpuchka/albert-heijn-mcp v1.7.1, for ah.be, without a login.
An MCP server for Albert Heijn Belgium (ah.be). It needs no account: with --anonymous it offers seven read-only tools (products, this week's bonus offers, bonus groups, product alternatives, recipes) and nothing that touches a login, a list or an order. It starts from the code of olekpuchka/albert-heijn-mcp v1.7.1 (see NOTICE) and does not follow upstream. A Belgian login is not part of v1. Upstream's README, for ah.nl and with a login, follows below.
Claude Desktop (.mcpb): download albert-heijn-be-mcp.mcpb from the releases page and double-click it, or go to Settings → Extensions → Advanced settings → Install Extension… and pick the file. It starts without a login (anonymous), contains everything it needs and needs no token.
docker run (Streamable HTTP on port 3000, AH_SITE=be, anonymous). The image needs no token:
docker run --rm --read-only -p 127.0.0.1:3000:3000 ghcr.io/arnouthoebreckx/albert-heijn-be-mcpThe MCP endpoint is http://127.0.0.1:3000/mcp; GET /healthz answers ok. Nothing authenticates a caller, so expose it only on a private network behind a gateway.
LiteLLM: add the container to the proxy's config.yaml. The tools then reach agents as ah_be-<tool>, for example ah_be-ah_search_products.
mcp_servers:
ah_be:
url: "http://albert-heijn-be-mcp:3000/mcp"
transport: "http"npx (stdio): GitHub's npm registry needs a token for every install, also of a public package. The image and the .mcpb need no token. Put these two lines in ~/.npmrc first (the token is a classic GitHub token with the read:packages scope):
@arnouthoebreckx:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<a classic GitHub token with read:packages>Then run it. It needs Node.js 24:
npx -y @arnouthoebreckx/albert-heijn-be-mcp --anonymousTo start it from a desktop app instead, add this to the app's MCP settings, for example claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"ah-be": {
"command": "npx",
"args": ["-y", "@arnouthoebreckx/albert-heijn-be-mcp", "--anonymous"]
}
}
}albert-heijn-mcp
Your Albert Heijn account, in your AI assistant.
Connect your Albert Heijn account to an AI assistant such as Claude, ChatGPT or Cursor, and do your grocery shopping by just asking. Find products and bonus deals, plan meals from Allerhande recipes, keep your shopping list and delivery order up to date, and look back at what you've bought.
Technically, it's a Model Context Protocol (MCP) server for Albert Heijn 🇳🇱. MCP is the standard way AI apps connect to other services, so it works with any app that supports MCP.
An unofficial project, not affiliated with or endorsed by Albert Heijn. It uses the same API as the AH mobile app, which may change without notice.
Contents
For everyone
Technical details
Running it on a server for ChatGPT and Claude.ai
Tools and limitations
Related MCP server: ah-mcp
What you can ask
Ask in Dutch, English or any language your assistant speaks:
"Wat is er deze week in de bonus van wat ik meestal koop?"
Plan meals
"Find a vegetarian Allerhande recipe under 30 minutes for two, and put the ingredients on my shopping list. I already have olive oil and salt."
"Scale the panlasagne recipe to six people and tell me how much salmon I need."
"Plan three weeknight dinners around what's on bonus this week."
Save money
"Which products I usually buy are on bonus this week?"
"Rebuild tonight's stir-fry with ingredients that are on bonus, without changing the recipe too much."
"Is next week's bonus out yet? If not, when does it appear?"
"What's in the 2+1 gratis kaas deal?"
Shop
"Put the products I've had delivered at least three times back on my list."
"Find organic, gluten-free pasta, cheapest first."
"Compare the protein and sugar in these three yoghurts and add the best one to my list."
"When can AH deliver on Saturday?"
"The courgettes are sold out. What else would work in this recipe?"
"Add two more packs of milk to my upcoming delivery."
"Make a favourites list called Pasta night with everything from this recipe."
"Any vandaag-af bread or vegetables at my local AH worth picking up tonight?"
Look back
"How much did my in-store receipts add up to in September, and what were the five priciest items?"
"Show the receipt from my last shop and list anything I bought more than once."
Getting started
You need an Albert Heijn account. Then:
Connect your app: pick yours below.
Log in to Albert Heijn: ask your assistant to log you in, once.
Ask away. See what you can ask.
Connecting a client
Your app | How |
Claude Desktop | Download and double-click. Easiest; nothing else to install. |
Cursor, VS Code | |
ChatGPT, Claude.ai (web and mobile) | Needs your own server (technical) |
Other apps |
Claude Desktop
Download
albert-heijn-be-mcp.mcpb.Double-click it and choose Install. If it doesn't open in Claude, go to Settings → Extensions → Advanced settings → Install Extension… and pick the file.
That's it: the file contains everything it needs. To update, do the same with the file from the newest release.
Other desktop apps that support MCP Bundles (.mcpb files) install it the same way.
Cursor and VS Code
Install Node.js 24 (LTS) and put the two ~/.npmrc lines from the top of this page in place first (GitHub's npm registry needs a token for every install), then click:
ChatGPT and Claude.ai
Web and mobile apps can't run anything on your computer; they only connect to servers on the internet. So you first need to run it on a server, which takes some technical know-how. Then add it as a connector:
ChatGPT needs Developer mode (Plus, Pro, Business, Enterprise and Education). Open Settings → advanced settings, turn on Developer mode, and create a connector with
https://your-server/mcp. Set authentication to OAuth.Claude.ai: Settings → Connectors → Add custom connector, paste
https://your-server/mcpand choose Connect.
The app then opens a login page on your server: enter your AH_MCP_TOKEN there, once.
Other apps
Apps that start MCP servers as a local command need Node.js 24 (LTS) and run npx -y @arnouthoebreckx/albert-heijn-be-mcp, which downloads and runs the latest version from GitHub Packages; it needs the two ~/.npmrc lines from the top of this page. Most of them take this JSON in their MCP settings:
{
"mcpServers": {
"ah": {
"command": "npx",
"args": ["-y", "@arnouthoebreckx/albert-heijn-be-mcp"]
}
}
}Where the settings live differs per app; see its documentation. Apps with a command line usually have an add command instead, e.g. <client> mcp add ah -- npx -y @arnouthoebreckx/albert-heijn-be-mcp. It is also listed in the MCP Registry, which some apps install from.
To install it permanently instead, run npm install --global @arnouthoebreckx/albert-heijn-be-mcp and use the albert-heijn-be-mcp command; run the same command again to update.
Desktop apps don't load your shell profile, so they may not findnpx (common with nvm). Then set command to the output of which npx.
Logging in
Belgium (--site be, the default): a Belgian login is not part of v1 and is not tested. The login tools point at login.ah.be, but nobody has checked that they work. For ah.be, run the server with --anonymous (see Configuration): it needs no login and serves search, products and the bonus.
Ask your assistant to log you in to Albert Heijn. You only do this once; the login is then kept and renewed automatically.
On your computer (Claude Desktop, Cursor, VS Code and other local apps), a separate browser window opens with AH's login page. Log in there as usual: the window closes by itself and you're logged in. Then tell your assistant you're done.
The window uses a fresh, empty browser profile, so type your password: saved passwords and password-manager extensions aren't available there. It needs Chrome, Edge, Brave or Chromium (not the snap version on Ubuntu) and a screen; otherwise you copy the code by hand as below.
On a server (ChatGPT, Claude.ai), or when no login window can open, you copy a code by hand. AH's login page has a captcha that only works on AH's own website, so the code has to come from your browser:
You need a computer for this, not a phone or tablet: their browsers have no developer console. Chrome, Edge or Brave work best.
Open the link your assistant gives you, but don't log in yet.
Open the developer console in that tab, a panel for web developers that you can open safely: ⌘ ⌥ J on Mac, or Ctrl Shift J on Windows and Linux.
Log in as usual. AH then tries to open its phone app, which your browser can't do, so the page seems stuck. In the console, find this red line:
Failed to launch 'appie://login-exit?code=…' because the scheme does not have a registered handler.Copy the part from
appie://up to the closing quote and paste it into the chat. The code works once and expires quickly, so paste it right away.
No line there? See Troubleshooting. To log a server in without the developer console, see Running it on a server.
Your login is saved on your own computer and renewed automatically, in a file only your user can read:
OS | Location |
macOS |
|
Linux |
|
Windows |
|
Override the location with AH_TOKENS_PATH.
Troubleshooting
The login window needs Chrome, Edge, Brave or Chromium installed in the usual place, and a screen: not over SSH, and not with Ubuntu's snap Chromium. Without one, your assistant gives you the link instead, and you copy the code by hand. If the window closed before you finished, ask to log in again.
The developer console has to be open before you log in. Open it, then open the login link again in that same tab and log in. If AH skips the login form because you're still logged in, that's fine: the line appears all the same. You can also look for the appie://login-exit?code=… request in the Network tab. Browsers other than Chrome, Edge or Brave may show the link in an error page or dialog instead.
Codes work once and expire quickly. Ask to log in again and paste the new link straight away.
Ask your assistant to log you out and back in, or delete tokens.json from the login location and log in again.
Albert Heijn no longer accepts the stored login. Ask your assistant to log in to Albert Heijn again. Reconnecting your app to the server doesn't help: that's a separate login.
If it keeps expiring on your server, keep tokens.json on storage that survives restarts and redeploys, and run a single instance. AH replaces the login every time it's renewed, so an older copy of the file, or a second instance renewing on its own, gets rejected.
A code never replaces a working login, so a code from someone else's account can't switch you over. To switch accounts, ask to log out first, then log in again.
AH accepts order changes only once an order exists. Choose a delivery slot in the AH app or on ah.nl first.
Choosing a slot moved your list into the order. Ask your assistant to change the order instead (ah_get_cart, ah_update_cart_item) until it is delivered or cancelled.
Set AH_MCP_TOKEN to a long random value, e.g. the output of openssl rand -hex 32, and restart. Changing it logs out every client; reconnect them once.
Start connecting again from the app. If it keeps happening right after you enter the token, check that AH_MCP_BASE_URL is exactly the address in your browser, including https://: the login form is only accepted from that address.
Set AH_MCP_BASE_URL to the server's public https:// URL and restart it. Apps are sent there to log in.
Set AH_MCP_PORT to another port, in the environment or .env.
Anonymous mode over HTTP, and the Docker image
With --anonymous the server needs no Albert Heijn account, and it registers only the tools that work without one: ah_search_products, ah_get_products, ah_get_bonus_offers, ah_get_bonus_group_products, ah_get_product_alternatives, ah_search_recipes and ah_get_recipe. ah_get_bonus_offers with previously_bought: true needs an account, so it returns an error.
Over Streamable HTTP, anonymous mode needs no OAuth and no AH_MCP_TOKEN: nobody logs in, and no account or personal data is behind it. It serves /mcp on AH_MCP_HOST (default 127.0.0.1) and AH_MCP_PORT (default 3000), and GET /healthz, which answers 200 with ok:
npx -y @arnouthoebreckx/albert-heijn-be-mcp --transport streamable-http --anonymousNothing authenticates a caller in this mode. Expose itonly on a private network behind a gateway (LiteLLM, or a reverse proxy that does the authentication), never directly on the internet.
The Docker image starts in this mode: AH_SITE=be, --anonymous, Streamable HTTP, listening on 0.0.0.0:3000. It runs as a non-root user, writes nothing to disk, holds no secrets and has a healthcheck on /healthz:
docker build -t albert-heijn-be-mcp .
docker run --rm --read-only -p 127.0.0.1:3000:3000 albert-heijn-be-mcpWithout --anonymous, Streamable HTTP is upstream's mode and still needs AH_MCP_TOKEN, see below.
Running it on a server
Web and mobile apps such as ChatGPT and Claude.ai need the server on the internet, over Streamable HTTP with HTTPS. The endpoint is https://your-server/mcp.
Apps log in with OAuth: add the endpoint with OAuth (or automatic) authentication, and the app opens a login page on your server. Enter your AH_MCP_TOKEN there once; the app then gets its own tokens and renews them. The server accepts only these OAuth tokens, not AH_MCP_TOKEN itself, so apps without OAuth support can't connect over HTTP; run them locally instead.
Anyone withAH_MCP_TOKEN can log in and use your Albert Heijn account. Use a long random value (openssl rand -hex 32). Changing it logs out every client.
It runs as a hardened systemd service behind a reverse proxy, installed from GitHub Packages, which needs a token (the two ~/.npmrc lines from the top of this page, for the user that runs npm install):
Prepare the server. Install Node.js 24 and create a service user:
sudo useradd -r -m -d /home/albert-heijn-be-mcp -s /sbin/nologin albert-heijn-be-mcpConfigure it in
/home/albert-heijn-be-mcp/.env:AH_MCP_BASE_URL=https://albert-heijn-be-mcp.example.com AH_MCP_TOKEN=<output of: openssl rand -hex 32>Make it readable only by the service:
sudo chown albert-heijn-be-mcp: /home/albert-heijn-be-mcp/.env && sudo chmod 600 /home/albert-heijn-be-mcp/.env.Install it with the service unit that comes with the package (it runs in
--remotemode):sudo npm install --global --prefix /usr/local --ignore-scripts @arnouthoebreckx/albert-heijn-be-mcp sudo install -m 644 /usr/local/lib/node_modules/@arnouthoebreckx/albert-heijn-be-mcp/deploy/albert-heijn-be-mcp.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now albert-heijn-be-mcpTo update, run the same commands, then
sudo systemctl restart albert-heijn-be-mcp.Add TLS with a reverse proxy that forwards to
127.0.0.1:3000. With Caddy:albert-heijn-be-mcp.example.com { reverse_proxy 127.0.0.1:3000 }
To log the server in to Albert Heijn, ask a connected app to log you in and copy the code by hand. Or skip the code: log in on your own computer with the login window, then copy the login to the server:
AH_TOKENS_PATH=./server-tokens.json npx -y @arnouthoebreckx/albert-heijn-be-mcp login
scp server-tokens.json your-server:ah-tokens.json && rm server-tokens.json
ssh -t your-server 'sudo sh -c "install -d -o albert-heijn-be-mcp -g albert-heijn-be-mcp -m 700 /home/albert-heijn-be-mcp/.config/albert-heijn-mcp && install -o albert-heijn-be-mcp -g albert-heijn-be-mcp -m 600 $HOME/ah-tokens.json /home/albert-heijn-be-mcp/.config/albert-heijn-mcp/tokens.json.new && mv /home/albert-heijn-be-mcp/.config/albert-heijn-mcp/tokens.json.new /home/albert-heijn-be-mcp/.config/albert-heijn-mcp/tokens.json && rm $HOME/ah-tokens.json"'The server picks it up on the next request; no restart needed. The separate file keeps your computer's own login apart: AH replaces a login every time it's renewed, so only one place can use each login. On a host without SSH, upload it to where the server keeps its login: AH_TOKENS_PATH, or the default location for the user it runs as.
The service can write only to /home/albert-heijn-be-mcp, where it keeps its tokens. If you point AH_LOG_FILE elsewhere, add that path to ReadWritePaths in the unit file.
Configuration
Settings are environment variables. They can also go in a .env file in the working directory (see .env.example); variables already set in the environment take precedence. On a hosting platform, set them in its environment variable or secret settings instead of a .env file, so AH_MCP_TOKEN stays out of the app's files.
Variable | Default | Description |
|
| The Albert Heijn site: |
|
|
|
| per site | Replaces the API host ( |
|
| Don't open a browser on login; log in by copying the code instead (same as |
| Where to store login tokens. | |
|
| Interface the HTTP server listens on. Keep the default behind a reverse proxy. |
|
| HTTP server port. |
|
| Public URL of the HTTP server. Set it on a server: OAuth clients are sent to this URL to log in, and for a non-local URL the localhost-only |
| — | Secret for the HTTP transport, at least 32 characters; the transport doesn't start without it, except with |
| — | Also append logs to this file. Logs always go to stderr. |
Command-line flags:
node dist/index.js [--site be|nl] [--anonymous] [--transport stdio|streamable-http] [--remote] [--version] [--help]
node dist/index.js login [--remote]stdio (the default) is for local clients; streamable-http serves MCP at /mcp, with OAuth login at /authorize (with --anonymous: no OAuth, and GET /healthz answers ok). login logs in to Albert Heijn from the terminal, saves the tokens and exits; with --remote it asks for the code instead of opening a login window.
Tools
These are what your assistant uses behind the scenes; you don't call them yourself. Read-only tools are marked as such, so apps can run them without asking. Tools that remove data are marked destructive, so apps ask for confirmation first.
Tools that return data also return it as structured output with a declared schema, for clients that use it. Products and recipes in tool results include a url to their page on ah.nl, and the server asks the assistant to link their names to it.
Tool | Description |
| Log in: opens a login window on your computer, or returns AH's login link and completes the login with the code you paste back. |
| Delete the stored tokens, to switch accounts or reset a session. |
| Name, masked email, and bonus card number (last 4 digits). |
Tool | Description |
| Search one or more keywords at once; Dutch terms work best. Filter by |
| Details for one or more products. |
| Similar products and substitutes AH suggests for a product. |
| This week's bonus offers, or next week's with |
| The individual products behind a group deal such as "2+1 gratis", |
| Nearby stores, by postal code or your own address. |
| Vandaag-af markdowns in a store; the one nearest your address by default. |
Every offer and product row of the search, product and group tools has the price fields pack_price (one pack on the shelf), deal_min_quantity, deal_total and deal_price_per_pack (the deal; null without one) and unit_price with unit_price_unit. Use them for a shopping line: original_price and bonus_price can be for two packs.
Tool | Description |
| Search Allerhande recipes; Dutch terms work best. |
| Ingredients, steps, and nutrition per serving. |
| Match a recipe's ingredients to products and add them to the list in one step. It prefers products on bonus ( |
Tool | Description |
| Your shopping list ("Mijn lijst"), the basket you fill while shopping. |
| Put products on the list, with a quantity each. |
| Add a free-text item, like "verse bloemen". |
| Remove products or free-text items. |
| Remove everything. Requires |
| Your favourite lists ("Mijn lijstjes"). |
| Add products to a favourite list. |
| Take products off a favourite list. |
| Start a new, empty favourite list. |
| Delete a favourite list and its items. Requires |
Choosing a delivery or pick-up slot in the AH app moves your shopping list into an order. ah_get_delivery_slots shows when delivery is possible; the other tools work on that order.
Tool | Description |
| Delivery windows at your address for the coming days. |
| Products in the active order, with total price and discount. |
| Change a product's quantity; 0 takes it out. |
| Remove a product from the order. |
| Remove everything from the order. Requires |
Tool | Description |
| Upcoming delivery orders, or past ones with |
| Products in one order. |
| Your most-ordered products, counted over your delivery orders. |
| Recent in-store receipts (kassabonnen). |
| Items, discounts and payment for one receipt. |
Limitations
Delivery orders can't be started through the API.
ah_get_delivery_slotslists the windows, but booking one, which starts the order, happens in the AH app or on ah.nl. While the order is active, AH doesn't serve the shopping list; the tools say so and point to the order tools.Ticking off shopping-list items isn't supported: the API returns no usable item IDs.
Bonus Box, AH's personal weekly deals, is not available: its API is unknown.
Limits per call: at most 99 of a product, 50 items, and 100 characters for a free-text item or list name.
Development
git clone https://github.com/arnouthoebreckx/albert-heijn-be-mcp
cd albert-heijn-be-mcp
npm ci
npm run build # compile to dist/
npm run lint # type-checkRun it from the checkout with node dist/index.js, or use /path/to/albert-heijn-be-mcp/dist/index.js as the argument in your client's config with node as the command.
Path | Contents |
Entry point, flags and settings, and the | |
Client for AH's REST and GraphQL API, on Node's built-in | |
Login window, login code exchange, token storage and refresh | |
Streamable HTTP transport and OAuth login | |
The MCP tools, one file per area | |
systemd unit, shipped in the package | |
Manifest of the | |
Name, descriptions and icon to use in connector settings and app directories (how) | |
CI, release workflow, Dependabot and the pinned | |
Logo for this README and the server icon shown by MCP clients |
The only runtime dependencies are the official MCP TypeScript SDK and Zod, which the SDK uses for tool schemas.
To call tools by hand, use the MCP Inspector:
npx @modelcontextprotocol/inspector node dist/index.jsBefore deploying a change, run a quick check against a real account: log in, search for melk, add a product to your shopping list and remove it again, then view your cart and orders.
To release, set the new version with npm version 1.2.3 --no-git-tag-version and in server.json (the version, the .mcpb URL and the image tag) and manifest.json, merge it to main, and push a tag: git tag v1.2.3 && git push origin v1.2.3. Only repository admins can create v* tags. The release workflow checks that the versions match, builds the package, attaches it to the GitHub release as albert-heijn-be-mcp.tgz together with the albert-heijn-be-mcp.mcpb bundle, attests the build provenance of the tarball and publishes it to GitHub Packages with the workflow's own token (no npm token is stored and nothing waits for an approval), and builds the multi-arch image and pushes it to ghcr.io/arnouthoebreckx/albert-heijn-be-mcp with build provenance. Once the .mcpb and the image are published, the registry job adds the .mcpb's SHA-256 to its copy of server.json and lists the .mcpb and the image in the MCP Registry through GitHub OIDC. The registry fetches the image without a token, so set the package public (under the repository's Packages) and re-run that job if the first run failed. The release starts without notes; write them on GitHub.
License
Available Tools
33 toolsah_add_free_text_to_shopping_listAlbert Heijn: Add Free-Text to Shopping ListA
Add a free-text item to the Albert Heijn shopping list (no product ID needed). Use for reminders like 'verse bloemen', 'any good wine', or items not found in search. Free-text items have no quantity: put amounts in the text, e.g. '2 bossen bloemen'.
Inputs: name (required).
ah_add_recipe_to_shopping_listAlbert Heijn: Add Recipe to Shopping ListA
Put the ingredients of an Allerhande recipe on the shopping list in one step. Each ingredient is matched to the AH product whose name fits it best (among equally good matches, one on bonus unless prefer_bonus=false); one unit of each product is added. Water is always skipped; pass skip for anything the user already has (e.g. olive oil, salt). Set dry_run=true to show the matches without adding them. Returns the added, skipped and unmatched ingredients, and any whose search failed (worth retrying). When you mention a product or recipe from the result, link its name to its url.
Inputs: recipe_id (required), skip, dry_run, servings, +1 more. Returns: added, failed, recipe, dry_run, +2 more
ah_add_to_favorite_listAlbert Heijn: Add to Favourite ListA
Add products to a named Albert Heijn favorite list. Get list_id from ah_get_favorite_lists.
Inputs: items (required), list_id (required).
ah_add_to_shopping_listAlbert Heijn: Add to Shopping ListA
Add one or more products to your Albert Heijn shopping list. Pass an array of items, each with product_id (int) and quantity (int). Returns confirmation listing the names of successfully added products.
Inputs: items (required).
ah_clear_cartAlbert Heijn: Clear OrderADestructive
Remove ALL items from the active Albert Heijn delivery order (not the shopping list). Irreversible — requires confirm="yes" to prevent accidental use.
Inputs: confirm (required).
ah_clear_shopping_listAlbert Heijn: Clear Shopping ListADestructive
Remove ALL items from the Albert Heijn shopping list. Irreversible — requires confirm="yes".
Inputs: confirm (required).
ah_create_favorite_listAlbert Heijn: Create Favourite ListA
Create a new, empty Albert Heijn favorite list with the given name; AH drops some punctuation, such as '-'. Returns its id; add products with ah_add_to_favorite_list.
Inputs: name (required). Returns: id, name, item_count, updated_at
ah_delete_favorite_listAlbert Heijn: Delete Favourite ListADestructive
Delete an Albert Heijn favorite list and everything on it. Irreversible — requires confirm="yes". Get list_id from ah_get_favorite_lists.
Inputs: confirm (required), list_id (required).
ah_get_bonus_group_productsAlbert Heijn: Bonus Group ProductsARead-only
Get the individual products belonging to a specific Albert Heijn bonus promotion group. Use this to drill into a deal like '2+1 gratis kaas' or 'Alle yoghurt 25% korting'. Get segment_id from the bonus_segment_id field in ah_get_bonus_offers results. Pages of limit products (default 25, at most 100) from offset; total is the size of the whole group. Every product has the group's category. An id that is not in that week's bonus, and period='next' on ah.be, are errors; an empty products list means the group has no products today. Returns the same fields as ah_search_products (image_url only with include_images=true), plus category. When you mention a product or recipe from the result, link its name to its url.
Inputs: segment_id (required), limit, offset, period, +1 more. Returns: total, period, products, valid_from, +1 more
ah_get_bonus_offersAlbert Heijn: Bonus OffersARead-only
Get Albert Heijn bonus/promotional offers. Use this (not ah_search_products) when the user asks what is on bonus/sale/discount. Returns this week's bonus by default; set period='next' for next week's bonus, which AH publishes a few days before the new bonus week starts. Every answer says which week it covers (period, valid_from, valid_until). Supports optional keyword filter to find e.g. cheese on bonus: set query='kaas'. Every offer has a category (AH's bonus category): the answer's categories lists every category of the week with its number of offers (offer_count, before any filter), so set categories to a list of those names to get only those, and food_only=true to leave out the non-food categories (household, drugstore, cooking and table items). Set previously_bought=true for offers on products the user bought before (AH's 'Eerder gekocht'). Group deals (e.g. '2+1 gratis', 'Alle yoghurt 25% korting') have no id but a bonus_segment_id — pass that to ah_get_bonus_group_products to see the individual products in the group. Returns id, bonus_segment_id, title, category, original_price, bonus_price, discount_percentage, bonus_mechanism, and the price fields pack_price, deal_min_quantity, deal_total, deal_price_per_pack, unit_price, unit_price_unit (use these for a shopping line: original_price and bonus_price can be for two packs). When you mention a product or recipe from the result, link its name to its url.
Inputs: limit, query, period, food_only, +2 more. Returns: offers, period, categories, valid_from, +1 more
ah_get_cartAlbert Heijn: View Order CartARead-only
View the items in the active Albert Heijn delivery order (the order cart). An order only exists after the user has chosen a delivery or pick-up slot; the products the user is collecting before that are on the shopping list (use ah_get_shopping_list). Returns the order state, items with names and quantities, total price, and total discount. When you mention a product or recipe from the result, link its name to its url.
Inputs: no named parameters. Returns: order
ah_get_delivery_slotsAlbert Heijn: Delivery SlotsARead-only
List the delivery time windows Albert Heijn offers at the member's address, per day (Dutch time). Booking a slot is only possible in the AH app or on ah.nl; this shows when delivery is possible. Returns date and windows like '15:00-17:00'.
Inputs: days. Returns: days, postal_code
ah_get_favorite_listsAlbert Heijn: View Favourite ListsARead-only
List all Albert Heijn favorite/saved shopping lists with their names and item counts. Use the returned list ID with ah_add_to_favorite_list, ah_remove_from_favorite_list or ah_delete_favorite_list.
Inputs: no named parameters. Returns: lists
ah_get_frequent_itemsAlbert Heijn: Frequently Ordered ItemsARead-only
Get frequently ordered products by analysing order history. Fetches all fulfillments, expands each order's items, counts per product, and returns products ordered at least min_order_count times. Returns product_name, product_id, order_count, last_ordered_date. When you mention a product or recipe from the result, link its name to its url.
Inputs: min_order_count. Returns: products
ah_get_last_chance_itemsAlbert Heijn: Last-Chance ItemsARead-only
Get last-chance / vandaag-af / clearance items from an Albert Heijn store. Requires a store_id (use ah_search_stores to find stores, or provide postal_code to find the nearest store). Uses the dedicated bargainItems GraphQL endpoint which returns today-only markdown deals. When you mention a product or recipe from the result, link its name to its url.
Inputs: limit, store_id, postal_code. Returns: items
ah_get_member_profileAlbert Heijn: Member ProfileARead-only
Get your Albert Heijn member profile. Returns name, email (masked), and bonus_card_number (last 4 digits only).
Inputs: no named parameters. Returns: name, email, bonus_card_number
ah_get_order_detailsAlbert Heijn: Order DetailsARead-only
Get the full item list for a specific Albert Heijn delivery order by its ID. Returns all products with names, quantities, and prices. Get order_id from ah_get_orders. When you mention a product or recipe from the result, link its name to its url.
Inputs: order_id (required). Returns: id, items, state, total_price, +1 more
ah_get_ordersAlbert Heijn: OrdersARead-only
List Albert Heijn online delivery orders. By default returns upcoming orders (with a modifiable flag); set past=true for delivered orders. Returns id, date, time_window, total_price, status. Use the returned id with ah_get_order_details to see the items.
Inputs: past, limit. Returns: orders
ah_get_product_alternativesAlbert Heijn: Product AlternativesARead-only
Get products Albert Heijn suggests instead of a given product: similar products and substitutes, e.g. when it is sold out or to find a cheaper or organic option. Returns the same fields as ah_search_products. When you mention a product or recipe from the result, link its name to its url.
Inputs: product_id (required), limit. Returns: products
ah_get_productsAlbert Heijn: Product DetailsARead-only
Get detailed information about one or more Albert Heijn products by ID (max 20). Returns title, brand, category, price, the price fields (pack_price, deal_min_quantity, deal_total, deal_price_per_pack, unit_price, unit_price_unit), unit size, bonus info, NutriScore, property icons. Set include_nutritional_info=true to also return calories, fat, protein, etc.; include_ingredients=true for the ingredients text and the allergens (what it contains or may contain); include_description=true for the description; include_images=true for image_url. Get product IDs from ah_search_products. When you mention a product or recipe from the result, link its name to its url.
Inputs: product_ids (required), include_images, include_description, include_ingredients, +1 more. Returns: products
ah_get_receipt_detailsAlbert Heijn: Receipt DetailsARead-only
Get full details of a single Albert Heijn in-store receipt (kassabon) by its id. Returns all purchased items with name, quantity, unit price and line total, plus any discounts and payment method. Get the id from ah_get_receipts first.
Inputs: id (required). Returns: id, items, payments, discounts
ah_get_receiptsAlbert Heijn: ReceiptsARead-only
List recent Albert Heijn in-store receipts (kassabonnen). Returns receipt id, date, and total amount. Use ah_get_receipt_details with the id to see individual items.
Inputs: limit. Returns: receipts
ah_get_recipeAlbert Heijn: RecipeARead-only
Get an Allerhande recipe by id: ingredients, preparation steps, and nutrition per serving. Set servings to scale the ingredient quantities. To shop for it, search the ingredients with ah_search_products and add them with ah_add_to_shopping_list. When you mention a product or recipe from the result, link its name to its url.
Inputs: recipe_id (required), servings. Returns: id, url, steps, title, +9 more
ah_get_shopping_listAlbert Heijn: View Shopping ListARead-only
Get the contents of the Albert Heijn shopping list (boodschappenlijst). In the AH app this is the basket the user fills while shopping; choosing a delivery slot moves its products into an order, after which the list is unavailable until the order is done (use ah_get_cart then). Returns item names, quantities, and product IDs. When you mention a product or recipe from the result, link its name to its url.
Inputs: no named parameters. Returns: items
ah_loginAlbert Heijn: Log InA
Log in to Albert Heijn. Call without arguments to start. On the user's own computer this usually opens a login window that finishes the login by itself. Otherwise it returns the AH login link and step-by-step instructions: show them to the user as given, in order (the developer console must be open before they log in). The user then copies a link like appie://login-exit?code=...; call ah_login again with code set to that link (or just the code) to finish. Codes are single-use and expire quickly. If already logged in, returns the account name; to switch accounts, call ah_logout first.
Inputs: code.
ah_logoutAlbert Heijn: Log OutADestructive
Log out of Albert Heijn by deleting the stored tokens. Use this to switch accounts or reset a broken session. After logout, call ah_login to authenticate again.
Inputs: no named parameters.
ah_remove_from_cartAlbert Heijn: Remove from OrderADestructive
Remove a single product from the active Albert Heijn delivery order. Use product_id from ah_get_cart. To remove products from the shopping list, use ah_remove_from_shopping_list.
Inputs: product_id (required).
ah_remove_from_favorite_listAlbert Heijn: Remove from Favourite ListADestructive
Remove products from a named Albert Heijn favorite list. Get list_id from ah_get_favorite_lists.
Inputs: list_id (required), product_ids (required).
ah_remove_from_shopping_listAlbert Heijn: Remove from Shopping ListADestructive
Remove one or more items from the Albert Heijn Boodschappenlijst. For product items pass product_ids; for free-text items pass names. Get product_ids from ah_get_shopping_list.
Inputs: names, product_ids.
ah_search_productsAlbert Heijn: Search ProductsARead-only
Search Albert Heijn (Dutch supermarket) products by keyword. Pass one or more queries (max 10) to search for several products in one call. Prefer Dutch search terms for best results: e.g. 'melk' (milk), 'kaas' (cheese), 'brood' (bread), 'kip' (chicken), 'appel' (apple). Set bonus=true to return only products currently on promotion; this also finds product promotions, such as volume discounts ('5% volume voordeel' on a 2-pack), that ah_get_bonus_offers does not list. filters narrows results to products matching all of them, e.g. ['organic', 'gluten_free']: organic, prijsfavoriet (AH's budget label), new, frozen, a diet (vegan, vegetarian, low_sugar, low_fat, low_salt), or free from an allergen (gluten_free, lactose_free, milk_free, egg_free, nut_free, peanut_free, soy_free, fish_free, shellfish_free, sesame_free, celery_free, mustard_free, lupin_free, sulphite_free). sort orders results: relevance (default), price_low_high, price_high_low, most_bought (by this user), nutriscore. Returns, per query: id, title, price, bonus_price, unit, is_bonus, bonus_mechanism, and the price fields pack_price, deal_min_quantity, deal_total, deal_price_per_pack, unit_price, unit_price_unit (image_url only with include_images=true). When you mention a product or recipe from the result, link its name to its url.
Inputs: queries (required), sort, bonus, limit, +2 more. Returns: searches
ah_search_recipesAlbert Heijn: Search RecipesARead-only
Search Allerhande, Albert Heijn's recipe collection. Dutch search terms work best, e.g. 'pasta', 'vegetarisch', 'stamppot', 'kip curry'. Returns id, title, url, cook_minutes, servings, courses, nutri_score, rating. Use the id with ah_get_recipe for ingredients and steps. When you mention a product or recipe from the result, link its name to its url.
Inputs: query (required), limit. Returns: total, recipes
ah_search_storesAlbert Heijn: Search StoresARead-only
Find Albert Heijn stores near a Dutch postal code. If no postal_code is given, automatically uses the address from the member profile. Returns store id (use this for ah_get_last_chance_items), name, type, and address.
Inputs: postal_code. Returns: stores
ah_update_cart_itemAlbert Heijn: Update Order ItemADestructive
Set the quantity of a product in the active Albert Heijn delivery order. Requires an order (started by choosing a delivery slot in the AH app or on ah.nl, which moves the shopping list into it); to collect products before that, use ah_add_to_shopping_list. Use product_id from ah_search_products or ah_get_cart. Set quantity=0 to remove the item (or use ah_remove_from_cart).
Inputs: quantity (required), product_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Most tools have clearly distinct resource/action targets, and descriptions explicitly distinguish cart vs shopping list vs favorite lists. Some overlap remains between product search, product details, alternatives, and bonus offers, but the boundaries are mostly explained well enough to avoid misselection.
Every tool uses the ah_ prefix and snake_case, with a predictable verb/resource pattern such as get_cart, search_products, add_to_shopping_list, and remove_from_favorite_list. The small variations (get/search/list/create) are semantically appropriate and consistent across the set.
The 33-tool surface is large for an agent to navigate reliably, even though the supermarket domain is broad. Several families of operations (cart, shopping list, favorites, bonus, orders) could be consolidated or grouped more tightly.
Coverage is strong across authentication, profile, products, recipes, cart, shopping list, favorites, orders, bonus offers, stores, and receipts. There are minor gaps such as no explicit add-to-cart or checkout/slot-booking operation, though some are platform limitations and can be partially worked around.
Maintenance
Related MCP Connectors
Independent directory of agentic AI tools — search, compare & recommend via MCP. Read-only.
Recipe search, ingredient matching, nutrition filters and a private cookbook for any AI agent.
Scraps Kitchen gives any AI agent a persistent, household-aware kitchen memory. Unlike generic chatbot recall, Scraps maintains structured cooking data: what's in your fridge (with freshness tracking), who you cook for (with allergens, dietary restrictions, and preferences), your recipe collection (with cook notes and per-diner ratings), your shopping list, and your kitchen equipment. 27 tools across 6 domains let agents read kitchen context, suggest meals that respect dietary safety, update the pantry after cooking, and build a history of what works for your household. Every interaction makes the data richer. Cooking history, preference signals, kitchen awareness = better suggestions next time. All tools work via oAuth and a free scraps.kitchen account.
Your kitchen in chat: pantry stock, shopping lists, recipes and scanned grocery receipts.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables querying live offers and prices from 10 Dutch supermarket chains through a single normalised JSON API. Exposes 26 curated tools, including product search and category lookups, over stdio or authenticated Streamable HTTP.201MIT
- 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
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to search grocery products, manage shopping carts, access account and order information, and find deals and delivery details across several European online grocery platforms.-
- AlicenseAqualityBmaintenanceEnables AI assistants to connect to Albert Heijn supermarket services for product search, Bonus promotions, shopping lists, digital receipts, Allerhande recipes, store lookup, and profile/cart access while keeping checkout human-controlled.271MIT