Albert Heijn

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.

[!NOTE]

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

• What you can ask
• Getting started: connect your app, then log in
• Troubleshooting

Technical details

• Running it on a server for ChatGPT and Claude.ai
• Configuration
• Tools and limitations
• Development

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."*

*"Put everything for the recipes in my AH meal planner on my shopping list."*

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?"*

*"Which of my personal offers are worth activating this week?"*

*"How many koopzegels do I have, and what are they worth?"*

*"What's in the 2+1 gratis kaas deal?"*

Shop

*"Put the products I buy most back on my list."*

*"What's this product, and is it on bonus?"* (with a photo of its barcode)

*"What's the cheapest cheese at AH right now?"*

*"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:

1. [Connect your app](#connecting-a-client): pick yours below.
2. [Log in to Albert Heijn](#logging-in): ask your assistant to log you in, once.
3. Ask away. See what you can ask.

Connecting a client

Claude Desktop

1. Download albert-heijn-mcp.mcpb.
2. 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) first, 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/mcp and 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 albert-heijn-mcp, which downloads and runs the latest version. Most of them take this JSON in their MCP settings:

{

"mcpServers": { "ah": { "command": "npx", "args": ["-y", "albert-heijn-mcp"] } } }

Where the settings live differs per app; see its documentation. Apps with a command line usually have an add command instead, e.g. mcp add ah -- npx -y albert-heijn-mcp. It is also listed in the MCP Registry, which some apps install from.

To install it permanently instead, run npm install --global albert-heijn-mcp and use the albert-heijn-mcp command; run the same command again to update.

[!TIP]

Desktop apps don't load your shell profile, so they may not find npx (common with nvm). Then set command to the output of which npx.

Logging in

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.

1. Open the link your assistant gives you, but don't log in yet.
2. 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.
3. 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.

1. 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.

Where your login is stored

Your login is saved on your own computer and renewed automatically, in a file only your user can read:

Override the location with AH_TOKENS_PATH.

Troubleshooting

No login window opens

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.

No "Failed to launch" line after logging in

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.

Login fails with "exchange code"

Codes work once and expire quickly. Ask to log in again and paste the new link straight away.

"Not logged in", or the session seems broken

Ask your assistant to log you out and back in, or delete tokens.json from the login location and log in again.

"The Albert Heijn login has expired"

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.

"Already connected as …" when pasting a login code

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.

"There is no active delivery order to change"

AH accepts order changes only once an order exists. Choose a delivery slot in the AH app or on ah.nl first.

"The shopping list is not available while a delivery order is active"

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.

<sum