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.

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

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:

1. Connect your app: pick yours below.
2. Log in to Albert Heijn: 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. <client> 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.

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:

   Copy

   Failed to launch 'appie://login-exit?code=…' because the scheme does not have a registered handler.
   

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

Troubleshooting

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.

It runs as a hardened systemd service behind a reverse proxy, installed from npm:

1. Prepare the server. Install Node.js 24 and create a service user:

   bashCopy

   sudo useradd -r -m -d /home/albert-heijn-mcp -s /sbin/nologin albert-heijn-mcp
   

2. Configure it in /home/albert-heijn-mcp/.env:

   envCopy

   AH_MCP_BASE_URL=https://albert-heijn-mcp.example.com
   AH_MCP_TOKEN=<output of: openssl rand -hex 32>
   

   Make it readable only by the service: sudo chown albert-heijn-mcp: /home/albert-heijn-mcp/.env && sudo chmod 600 /home/albert-heijn-mcp/.env.

3. Install it with the service unit that comes with the package (it runs in --remote mode):

   bashCopy

   sudo npm install --global --prefix /usr/local --ignore-scripts albert-heijn-mcp
   sudo install -m 644 /usr/local/lib/node_modules/albert-heijn-mcp/deploy/albert-heijn-mcp.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now albert-heijn-mcp
   

   To update, run the same commands, then sudo systemctl restart albert-heijn-mcp.

4. Add TLS with a reverse proxy that forwards to 127.0.0.1:3000. With Caddy:

   Copy

   albert-heijn-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 albert-heijn-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-mcp -g albert-heijn-mcp -m 700 /home/albert-heijn-mcp/.config/albert-heijn-mcp && install -o albert-heijn-mcp -g albert-heijn-mcp -m 600 $HOME/ah-tokens.json /home/albert-heijn-mcp/.config/albert-heijn-mcp/tokens.json.new && mv /home/albert-heijn-mcp/.config/albert-heijn-mcp/tokens.json.new /home/albert-heijn-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-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.

Command-line flags:

node dist/index.js [--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. 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.

Limitations

• Delivery orders can't be started through the API. ah_get_delivery_slots lists 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/olekpuchka/albert-heijn-mcp
cd albert-heijn-mcp
npm ci
npm run build    # compile to dist/
npm run lint     # type-check

Run it from the checkout with node dist/index.js, or use /path/to/albert-heijn-mcp/dist/index.js as the argument in your client's config with node as the command.

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

Before 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 both places in server.json and in 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-mcp.tgz together with the albert-heijn-mcp.mcpb bundle, and stages the package on npm through trusted publishing, so no npm token is stored. Approve the staged version on npmjs.com (or with npm stage approve) to make it live; the workflow then updates the MCP Registry entry. The release starts without notes; write them on GitHub.

License

Apache 2.0