Albert Heijn

[Image]

albert-heijn-mcp

[npm] [License: Apache-2.0] [Node.js 24] [MCP]

Your Albert Heijn account, in your AI assistant.

albert-heijn-mcp is a Model Context Protocol server for Albert Heijn 🇳🇱. Connect it to any MCP client and just ask: 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.

[!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

• What you can ask
• Quick start
• Logging in
• Connecting a client
• Configuration
• Deploying to a server
• Tools and limitations
• Development
• Troubleshooting

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

Quick start

Requirements: Node.js 24 (LTS) and an Albert Heijn account.

There's nothing to install: connect a client with npx -y albert-heijn-mcp, which downloads and runs the latest version, then ask it to log you in to Albert Heijn.

To install it permanently instead, run npm install --global albert-heijn-mcp and use the albert-heijn-mcp command. To build from source, clone the repository.

Logging in

AH's login page has a captcha that only works on AH's own site, so logging in takes two steps:

1. Ask your assistant to log you in. It calls ah_login and gives you a link to AH's login page; locally, it also opens in your browser. Log in as usual.

2. Paste the code back. After you log in, AH redirects to a link meant for its iPhone app, which the browser can't open, so the page stays put. Open the developer console (Chrome: ⌘ ⌥ J on Mac, Ctrl Shift J on Windows/Linux) and find this line:

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

   Copy the appie://login-exit?code=… link into the chat. The code works once and expires quickly, so paste it right away.

You only log in once. Tokens are stored on your machine and refreshed automatically:

The file is readable only by your user. Override the location with AH_TOKENS_PATH.

Connecting a client

albert-heijn-mcp works with any MCP client. It runs locally over stdio, or on a server over Streamable HTTP.

Local clients (stdio)

Install it in one click:

[Install in Cursor] [Install in VS Code] Other clients that start MCP servers as a local command run npx -y albert-heijn-mcp. 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 client; see its documentation. Clients with a CLI 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 clients install from.

[!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. For a source checkout, use node with the argument /path/to/albert-heijn-mcp/dist/index.js.

Remote clients (Streamable HTTP)

Web apps such as ChatGPT and Claude.ai only connect to servers on the internet. Set one up first (Deploying to a server). The endpoint is https://your-server/mcp.

Clients that support OAuth log in to the server themselves: add the endpoint with OAuth (or automatic) authentication, and the client opens a login page on your server. Enter your AH_MCP_TOKEN there once; the client then gets its own tokens and renews them. Clients without OAuth send AH_MCP_TOKEN as an Authorization: Bearer YOUR_TOKEN header, or in the URL as https://your-server/mcp?token=YOUR_TOKEN.

ChatGPT: needs Developer mode (Plus, Pro, Business, Enterprise and Education). Open Settings → advanced settings, turn on Developer mode, and create a connector with the endpoint. Set authentication to OAuth.

Claude.ai: Settings → Connectors → Add custom connector, then paste the endpoint and choose Connect.

[!IMPORTANT] Anyone with AH_MCP_TOKEN can use your Albert Heijn account. Use a long random value (openssl rand -hex 32). Changing it also logs out every OAuth client. A token in a URL can end up in proxy logs, so prefer OAuth or the header.

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.

Command-line flags:

node dist/index.js [--transport stdio|streamable-http] [--remote] [--version] [--help]

stdio (the default) is for local clients; streamable-http serves MCP at /mcp, with OAuth login at /authorize.

Deploying to a server

albert-heijn-mcp runs as a hardened systemd service behind a reverse proxy, installed from the latest release.

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

   bash

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

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

   env

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

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

   bash

   sudo npm install --global --prefix /usr/local albert-heijn-mcpsudo install -m 644 /usr/local/lib/node_modules/albert-heijn-mcp/deploy/albert-heijn-mcp.service /etc/systemd/system/sudo systemctl daemon-reloadsudo 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:

   albert-heijn-mcp.example.com {    reverse_proxy 127.0.0.1:3000}

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.

Tools

Read-only tools are marked as such, so clients can run them without asking. Tools that remove data are marked destructive, so clients 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.

Development

git clone https://github.com/olekpuchka/albert-heijn-mcpcd albert-heijn-mcpnpm cinpm 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 in package.json and in both places in server.json, merge it to main, and push a tag: git tag v1.2.3 && git push origin v1.2.3. The release workflow checks that the versions match, builds the package, attaches it to the GitHub release as albert-heijn-mcp.tgz, and stages it 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.

Troubleshooting

License

Apache 2.0