albert-heijn-mcp

<p align="center"><img src="assets/logo.png" alt="" width="128" height="128"></p>

# albert-heijn-mcp

[![npm](https://img.shields.io/npm/v/albert-heijn-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/albert-heijn-mcp)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Node.js 24](https://img.shields.io/badge/node-24%20LTS-339933?logo=node.js&logoColor=white)](.nvmrc)
[![MCP](https://img.shields.io/badge/MCP-server-6E56CF)](https://modelcontextprotocol.io)

**Your Albert Heijn account, in your AI assistant.**

albert-heijn-mcp is a [Model Context Protocol](https://modelcontextprotocol.io) 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](#what-you-can-ask)
- [Quick start](#quick-start)
- [Logging in](#logging-in)
- [Connecting a client](#connecting-a-client)
- [Configuration](#configuration)
- [Deploying to a server](#deploying-to-a-server)
- [Tools](#tools) and [limitations](#limitations)
- [Development](#development)
- [Troubleshooting](#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](#connecting-a-client) with `npx -y albert-heijn-mcp`, which downloads and runs the [latest version](https://www.npmjs.com/package/albert-heijn-mcp), 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](#development), 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: <kbd>⌘</kbd> <kbd>⌥</kbd> <kbd>J</kbd> on Mac, <kbd>Ctrl</kbd> <kbd>Shift</kbd> <kbd>J</kbd> 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:

| OS | Location |
|---|---|
| macOS | `~/Library/Application Support/albert-heijn-mcp/tokens.json` |
| Linux | `~/.config/albert-heijn-mcp/tokens.json` |
| Windows | `%AppData%\albert-heijn-mcp\tokens.json` |

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](https://img.shields.io/badge/Cursor-Install_server-000000?logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=ah&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImFsYmVydC1oZWlqbi1tY3AiXX0%3D)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF)](https://insiders.vscode.dev/redirect/mcp/install?name=ah&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22albert-heijn-mcp%22%5D%7D)
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:

```json
{
  "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](https://registry.modelcontextprotocol.io), 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](#deploying-to-a-server)). The endpoint is `https://your-server/mcp`.

Clients log in with OAuth: 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. The server accepts only these OAuth tokens, not `AH_MCP_TOKEN` itself, so clients without OAuth support can't connect over HTTP; run them locally over [stdio](#local-clients-stdio) instead.

**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 log in and use your Albert Heijn account. Use a long random value (`openssl rand -hex 32`). Changing it logs out every client.

## Configuration

Settings are environment variables. They can also go in a `.env` file in the working directory (see [`.env.example`](.env.example)); variables already set in the environment take precedence.

| Variable | Default | Description |
|---|---|---|
| `AH_REMOTE` | `false` | Don't open a browser on login (same as `--remote`). Always on with `streamable-http`. |
| `AH_TOKENS_PATH` | [per OS](#logging-in) | Where to store login tokens. |
| `AH_MCP_HOST` | `127.0.0.1` | Interface the HTTP server listens on. Keep the default behind a reverse proxy. |
| `AH_MCP_PORT` | `3000` | HTTP server port. |
| `AH_MCP_BASE_URL` | `http://localhost:3000` | 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 `Host` check is turned off so a reverse proxy can forward requests. |
| `AH_MCP_TOKEN` | — | Secret for the HTTP transport, at least 32 characters; the transport doesn't start without it. You enter it on the OAuth login page; it also signs the OAuth tokens. |
| `AH_LOG_FILE` | — | Also append logs to this file. Logs always go to stderr. |

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

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.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](deploy/albert-heijn-mcp.service) that comes with the package (it runs in `--remote` mode):

   ```bash
   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:

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

The service can write only to `