delhaize-mcp

An unofficial Model Context Protocol server that lets an AI assistant fetch your own Delhaize (Belgium) till receipts and this week's promotions, using its own headless browser, without driving your everyday browser and without ever seeing your password.

Unofficial and not affiliated with or endorsed by Delhaize. It reads only your own account, at your request, the way you would read it yourself. Check that your use fits Delhaize's terms of use, keep the request rate low, and do not use it to collect other people's data.

What it does

It never transcribes items, never edits your record, and never handles your password. It only puts files on disk. Reading the images and recording them is left to you or your assistant, ideally with a check that each receipt's lines sum to its printed total.

Receipts are identified by (date, store, total), so nothing is fetched twice.

Requirements

• Python 3.10+
• A Delhaize account with receipts linked to your loyalty card

Install

pip install delhaize-mcp
python3 -m playwright install chromium

This gives you two commands: delhaize-mcp (the MCP server) and delhaize-receipts (the same actions from the command line).

Set up

1. Log in once. A browser window opens, and you sign in yourself:

   delhaize-receipts login
   

   The session is saved in ~/.delhaize-mcp/profile (or set DELHAIZE_PROFILE). Later runs reuse it headlessly. If it lapses, run login again. That folder holds your session cookies: never commit or share it.

2. Choose a data folder (optional). By default everything is written to ~/.delhaize-mcp/data. Set DELHAIZE_DATA_DIR to use another folder. Your record of receipts is receipts_all.json in that folder, a JSON list such as:

   [{"date": "2026-08-11", "store": "Delhaize Centre", "total": 11.11, "image": "photos/2026-08-11.jpeg"}]
   

   image is optional. A receipt without an existing image is what backfill looks for.

3. Connect it to your assistant.

   Claude Code:

   claude mcp add delhaize-receipts -- delhaize-mcp
   

   Claude Desktop (claude_desktop_config.json):

   {
     "mcpServers": {
       "delhaize-receipts": {
         "command": "delhaize-mcp",
         "env": {"DELHAIZE_DATA_DIR": "/path/to/your/data"}
       }
     }
   }
   

   If the app cannot find delhaize-mcp, use its full path (which delhaize-mcp shows it).

Command line

The same actions work without an assistant:

delhaize-receipts status
delhaize-receipts list     --months 1   # this month and last
delhaize-receipts fetch    --months 1
delhaize-receipts backfill --months 3
delhaize-receipts promos

How it works

Delhaize renders each receipt as an image inside a client-side app, so the server lets the real page render in a headless Chromium (Playwright) and reads the finished page, exactly as a person would. All parsing rules (French dates, euro amounts, de-duplication, file naming) live in src/delhaize_mcp/core.py, which has no browser dependency and is fully unit-tested.

Tests

No browser or network needed:

python3 tests/test_core.py
python3 tests/test_server.py

Privacy

• Nothing leaves your machine except the normal page requests to delhaize.be.
• No password is read or stored. The login is a browser profile you create yourself.
• Your login and data live in ~/.delhaize-mcp, outside the code, so they never end up in a repository.

Limitations

• Built against the French-language Belgian site (delhaize.be/fr). Page changes on Delhaize's side can break it; the parsers are deliberately forgiving, and the tools report what they missed rather than failing silently.
• The promotions capture saves raw page data only; interpreting it is up to you.

Licence

MIT. See LICENSE.