albertheijn-mcp

What it does

albertheijn-mcp is an MCP server that runs on your own machine. It connects Claude, ChatGPT, Codex, Cursor, VS Code or any other MCP client to Albert Heijn, the Dutch supermarket. Your assistant can search the full assortment with prices, nutrition and allergens, see this week's bonus, find Allerhande recipes or import a recipe from any website, and turn a meal prep plan into a priced shopping list. Once you sign in it can also work with your shopping list, your booked order, past orders and in-store receipts.

It uses the same API as the Albert Heijn app. Nothing changes in a booked order until you have seen a preview and said yes.

Things you can ask once it is connected:

• Plan five high-protein lunches for next week, under 30 euros, and put them in my basket.

• What is on bonus this week that I usually buy?

• Which Greek yoghurt gives the most protein per euro?

• Shop for this recipe for four people: https://www.leukerecepten.nl/recepten/kip-tandoori/

• When is the cheapest delivery slot this weekend?

• How much did I spend at Albert Heijn per month since the summer?

• Is this product vegan, and does it contain gluten? (barcode 8710400058519)

Related MCP server: ah-mcp

Install

macOS and Linux:

curl -fsSL https://danieltyukov.github.io/albertheijn-mcp/install.sh | sh

Windows (PowerShell):

irm https://danieltyukov.github.io/albertheijn-mcp/install.ps1 | iex

The installer checks for Node.js 20 or newer, installs the package, and writes the MCP config for the clients it finds. You can also install the release tarball with npm directly:

npm install -g https://github.com/danieltyukov/albertheijn-mcp/releases/latest/download/albertheijn-mcp.tgz
albertheijn-mcp setup

Then, if you want the account features, sign in once:

albertheijn-mcp login

A Chrome, Edge, Chromium or Brave window opens on the Albert Heijn login page. You sign in there as usual and the window closes by itself. Products, bonus, recipes, stores and meal planning work without signing in.

Connect a client

albertheijn-mcp setup finds the MCP clients installed on your machine and adds the server to their config. It supports Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Codex, Gemini CLI and Cline. Add --dry-run to see what it would write, or name the clients you want, for example albertheijn-mcp setup cursor. docs/clients.md has the config for each client.

Any other client:

{
  "mcpServers": {
    "albertheijn": {
      "command": "albertheijn-mcp",
      "args": ["serve"]
    }
  }
}

Desktop apps such as Claude Desktop do not read your shell's PATH. If yours cannot start albertheijn-mcp, albertheijn-mcp setup --dry-run prints the same entry with absolute paths.

ChatGPT needs a public URL. Run albertheijn-mcp serve --http --tunnel and paste the printed URL into ChatGPT's connector settings.

Tools

docs/tools.md lists every input. The server also ships four prompts: meal_prep, weekly_shop, cook_from_bonus and recipe_to_basket.

Meal prep

plan_meal_prep takes recipes and the number of servings you want of each. A recipe can be an Allerhande recipe, a URL from another recipe site, or a plain list of ingredient lines. The server then:

1. reads each ingredient line in Dutch or English, including fractions, ranges and spoons;

2. scales each recipe and merges ingredients that appear in more than one;

3. finds the Albert Heijn product for each ingredient (for Allerhande recipes it uses Albert Heijn's own suggestion);

4. works out how many packs to buy and what is left over;

5. prices the whole basket with this week's bonus, as Albert Heijn would at checkout.

It skips salt, pepper, oil and other pantry staples unless you ask for them. You choose between the best match, the cheapest way to cover each amount, or products on bonus. The result includes the items for prepare_basket_change. Picking the recipes is left to the assistant: it can search Allerhande, import recipes from the web, or come up with its own.

How ordering works

In the Albert Heijn app, the shopping list and the online order share one basket. Before a delivery is booked, the basket is just your list. After you book a delivery or pick-up slot, everything in it becomes the order and is delivered and charged.

• While nothing is booked, update_shopping_list changes the list directly.

• Once a delivery is booked, list changes are refused. prepare_basket_change shows each product with its quantity before and after, the order total before and after with bonus, and the closing time. confirm_basket_change applies exactly that preview, only once, and only if the basket has not changed in the meantime.

• Booking the delivery slot and paying stay in the Albert Heijn app. get_delivery_slots shows the slots and what each one costs, so the assistant can tell you which to pick.

Sign-in and privacy

albertheijn-mcp login opens a separate browser profile on Albert Heijn's own login page and catches the code that the page normally hands to the app. The server swaps that code for tokens and stores them in ~/.albertheijn-mcp/session.json, readable only by you. On Windows the file is also encrypted with Windows data protection. Tokens renew automatically. No tool ever returns them, and only the last four digits of your Bonus card are shown.

Everything runs on your machine. The server talks to api.ah.nl and login.ah.nl, plus any web page you ask it to read. read_web_page and import_recipe refuse local and private network addresses, check each redirect, and return page text marked as untrusted. albertheijn-mcp logout deletes the session and the browser profile.

No browser on the machine, or the login page refuses the window it opens? Run albertheijn-mcp login --manual. It prints the login address. Open it in your normal browser with the developer tools open on the Network tab, sign in, and paste back the appie://login-exit?code=... address the page redirects to.

Requirements

• Node 20 or newer.

• For signing in: Google Chrome, Microsoft Edge, Chromium or Brave, or albertheijn-mcp browser install to download Chromium.

• An Albert Heijn account for the account features. Albert Heijn delivers in the Netherlands; the assortment and recipes are in Dutch.

Development

npm ci
npm run check          # typecheck, lint, unit tests, build
npm run test:e2e       # build, then drive the real CLI over stdio against a local mock API
npm run test:live      # read-only checks against the real API, no account needed
npm run dev -- status  # run the CLI from source

Unit tests use recorded responses and a mocked fetch. The end-to-end tests start node dist/cli.js serve the way an MCP client does and talk to it over stdio. The live tests call api.ah.nl. With AH_MCP_LIVE_ACCOUNT=1 on a signed-in machine they also check the account tools: they add an item to your list, check it, remove it again, and never confirm a change to a booked order. A scheduled workflow runs the anonymous live tests every week to catch API changes.

docs/design.md explains the design decisions, and docs/api.md lists every Albert Heijn endpoint the server uses, with what was verified and when.

Contributing

See CONTRIBUTING.md. Report security problems through SECURITY.md.

Credits

The API notes build on work by appie-go, fedorov-xyz/ah-mcp, mrserzhan/ah-mcp, openclaw-skill-albert-heijn and Albert-Heijn-OpenAPI.

License

MIT. See LICENSE.

This is an independent project. It is not made, endorsed or supported by Albert Heijn or Ahold Delhaize. "Albert Heijn", "Allerhande" and "Bonus" are their trademarks. The API it uses is undocumented and can change at any time.