mcp-intermarche-drive

Unofficial MCP server for Intermarché Courses / Drive. It searches the catalogue of the store selected in Intermarché and reads or updates the current basket through one visible Chromium tab.

It does not place orders. Checkout, payment, account changes, and delivery-slot booking stay on the website.

Current status

This is an early adapter for a private, undocumented web API.

• TypeScript build, unit tests, MCP initialization, tools/list, and tool annotations pass locally.
• Product search and basket retrieval were checked against the live Intermarché frontend on 2026-07-27.
• Basket writes are covered by tests against the event contract observed in the site. The automated live smoke test is deliberately read-only, so it does not prove that every write still works after an Intermarché release.
• The project is not published to npm. Install it from source.

Review the basket in the visible Intermarché tab before checkout. A green test suite cannot make an undocumented retail API stable.

Why the browser is part of the design

Intermarché puts DataDome in front of its shopping site. A separate HTTP client with copied cookies is both fragile and a poor security boundary. This server uses the browser session that the user can already see:

1. It attaches to Chromium over the Chrome DevTools Protocol (CDP).
2. It keeps one Intermarché tab on https://www.intermarche.com.
3. It runs window.fetch in that page, so the browser applies its own cookies and challenge state.
4. It serializes requests and adds a small delay between them.
5. If DataDome shows a challenge, the server stops retrying and tells the user to handle it in the browser.

This is not a CAPTCHA solver or a DataDome bypass. Login, store selection, challenge handling, and checkout remain visible browser actions.

The adapter does not export the browser cookie jar. Its page helper extracts only the values derived from itm_device_id and itm_usid, which Intermarché's frontend sends as request headers. Those values stay in process memory and never appear in MCP results, logs, or project files. See security boundaries for the limits of that guarantee.

What came from the Leclerc reference

The browser/CDP and throttling approach was adapted from skunkobi/mcp-leclerc-drive. The Intermarché implementation is not a renamed Leclerc client:

Area	Leclerc reference	This project
Store	Locator tools plus a persisted store/host	Store and Drive mode come from the visible Intermarché tab
Catalogue	Product records parsed from store HTML	JSON product endpoint under www.intermarche.com
Basket	Form-encoded mutations and HTML cart extraction	Event-based JSON synchronization with the previous basket snapshot
Substitutions	No separate contract	Explicit tool; additions default to refusal
Browser target	General page target reused for the store host	One Intermarché tab, or one blank tab; unrelated tabs are left alone

The full design review is in docs/design-review.md. Upstream attribution and license text are in NOTICE.

Tools

Tool	Reads or writes	Contract
browser_status	Read	Reports CDP state, active store reference, delivery mode, whether a basket id was found, and visible DataDome action required.
search_product	Read	Searches the active store. Returns Intermarché itemId values for basket tools.
get_cart	Read	Returns the complete normalized basket and total.
add_to_cart	Write	Increases the current quantity by quantity. Substitutions default to false.
update_quantity	Write	Sets an absolute quantity. 0 removes the line.
remove_from_cart	Write	Removes one product line.
set_substitution	Write	Sets substitution consent for a product already in the basket.

product_id means the id returned by search_product or get_cart. It is normally Intermarché's itemId, not the EAN printed on the package.

Cart mutations happen as soon as the MCP client calls the tool. There is no second confirmation layer inside this server; the MCP host is responsible for its own approval UI.

Requirements

• Node.js 22 or newer. The server uses Node's built-in WebSocket.
• A visible Chromium-family browser with CDP enabled.
• A graphical desktop session. Automatic launch is not suitable for a display-less server.
• An Intermarché store and the Drive withdrawal mode selected in the dedicated browser profile.

Automatic browser detection currently expects:

• macOS: Google Chrome in /Applications;
• Windows: Google Chrome in Program Files;
• Linux: a chromium executable on PATH.

Set INTERMARCHE_CHROME_PATH when your browser lives elsewhere, such as google-chrome on Linux.

Install from source

git clone https://github.com/nicolasestrem/mcp-intermarche-drive.git
cd mcp-intermarche-drive
npm ci
npm run build
npm test
npm run smoke

The repository is private, so the clone command requires GitHub access to it.

The executable entry point after the build is:

/absolute/path/mcp-intermarche-drive/dist/src/index.js

Connect an MCP client

Use the built file as a local stdio server. The common JSON form is:

{
  "mcpServers": {
    "intermarche-drive": {
      "command": "node",
      "args": ["/absolute/path/mcp-intermarche-drive/dist/src/index.js"],
      "env": {
        "INTERMARCHE_AUTO_LAUNCH": "true"
      }
    }
  }
}

Replace the path with the real absolute path. Do not use npx mcp-intermarche-drive; there is no published package.

The server is lazy about browser startup. Starting the MCP process does not open Chromium immediately. The first tool call that needs the browser, normally browser_status, connects to CDP and launches the dedicated profile if necessary.

First use

1. Start or reload the MCP client after adding the configuration.
2. Call browser_status. A dedicated Chromium profile should open on CDP port 9222.
3. In its single tab, open Intermarché if needed.
4. Select the intended store and the Drive withdrawal mode.
5. Log in if you want to use the account basket. Anonymous baskets also work when the site permits them.
6. Resolve any DataDome challenge in the visible tab.
7. Call browser_status again, then try a product search.

Keep one Intermarché tab in this profile. Multiple tabs can hold different store or basket state, and the server has no sensible way to guess which one you meant.

Attach to a browser you launch yourself

Set automatic launch off in the MCP environment:

{
  "env": {
    "INTERMARCHE_AUTO_LAUNCH": "false",
    "INTERMARCHE_CHROME_PORT": "9222"
  }
}

Then start Chromium with a dedicated profile and a loopback-only debugging endpoint:

chromium \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.mcp-intermarche-drive/chrome" \
  --no-first-run \
  --no-default-browser-check \
  about:blank

Do not point this server at your everyday browser profile. CDP grants control over the attached tab, and the profile directory contains a persistent browser session.

Configuration

Variable	Default	Meaning
INTERMARCHE_CHROME_PORT	9222	Loopback CDP port.
INTERMARCHE_CHROME_PATH	platform default	Chromium or Chrome executable.
INTERMARCHE_CHROME_PROFILE_DIR	~/.mcp-intermarche-drive/chrome	Dedicated persistent browser profile.
INTERMARCHE_AUTO_LAUNCH	true	Launch the browser when no CDP endpoint is listening.
INTERMARCHE_HEADLESS	false	Unsupported for normal use; it is more likely to trigger anti-bot checks and removes manual challenge handling.
INTERMARCHE_PDV_REF	browser-derived	Diagnostic fallback for store discovery. It must match the store selected in the tab. It does not switch stores.
INTERMARCHE_CATALOG_ID	641	Compatibility metadata fallback reported in browser context. It does not choose the store catalogue.
INTERMARCHE_MIN_INTERVAL_MS	1100	Minimum delay between queued web requests.
INTERMARCHE_JITTER_MS	500	Random delay added to the minimum.
INTERMARCHE_MAX_RETRIES	2	Bounded retries for HTTP 403 and 429.
INTERMARCHE_BACKOFF_BASE_MS	1800	Base for exponential retry backoff.
INTERMARCHE_CDP_TIMEOUT_MS	30000	Timeout for CDP commands and browser fetches.

Avoid setting INTERMARCHE_PDV_REF unless browser-state discovery is broken. An override that points at another store can mix that store's API path with the basket state held by the visible tab.

Security boundaries

• CDP is account-level browser access. Keep it on 127.0.0.1; never expose port 9222 to a LAN, container bridge, tunnel, or public interface.
• Use a dedicated profile only for Intermarché. Any local process that can access the CDP port or profile directory should be treated as trusted.
• Browser cookies still accompany same-origin requests because the fetch runs in the page. The server does not return the cookie jar through MCP or persist cookie values itself.
• The browser-state snapshot is limited to store and basket keys. Do not replace it with a dump of local storage when debugging.
• Cart tools modify the real current basket. There is no checkout tool, but basket changes are still external side effects.
• Use the project only with your own account and in accordance with the site's terms.

Troubleshooting

browser_status says CDP is unavailable

• Check that the configured browser executable exists.
• Check that another process is not using the port: change INTERMARCHE_CHROME_PORT on both the browser and MCP server if needed.
• On Linux, set INTERMARCHE_CHROME_PATH=google-chrome if chromium is not installed.
• On a remote or headless machine, launch the visible browser in the desktop session and use INTERMARCHE_AUTO_LAUNCH=false.

No active store is found

Select the store and Drive mode in the attached tab, then call browser_status again. Store selection belongs to the website. INTERMARCHE_PDV_REF is a last-resort fallback, not a replacement for the visible selection.

DataDome or HTTP 403/429

Stop calling tools. Bring the existing Intermarché tab to the expected page, complete any visible challenge, and wait before retrying. Do not open more tabs or increase the retry count to hammer through it.

If the browser session or login changed, restart the MCP process so cached request identifiers are rebuilt from the current page.

The wrong basket or store appears

Close extra Intermarché tabs in the dedicated profile. Remove a stale INTERMARCHE_PDV_REF override. Confirm the store and withdrawal mode in the website before making another cart change.

Chromium reports that the profile is already in use

Reuse the already-running CDP instance on the configured port, or close that dedicated Chromium process before starting another one. Do not reuse the same profile directory from two browser processes.

Development and verification

npm run typecheck
npm test
npm run smoke
npm audit --audit-level=low
npm pack --dry-run

What these checks cover:

• browser-state extraction from a narrow set of keys;
• normalization of current product and basket response shapes;
• absolute quantity and explicit substitution events;
• serialization of concurrent cart mutations;
• a real JSON-RPC initialize and tools/list exchange over stdio;
• MCP read-only, idempotent, and destructive annotations.

The optional live smoke test connects to the configured browser and performs only browser_status, product search, and basket retrieval:

npm run build
INTERMARCHE_AUTO_LAUNCH=false npm run smoke:live

It does not add or remove products. Run it manually, never as unattended public CI.

Adapter details and the revalidation checklist live in:

• docs/api-notes.md
• docs/design-review.md

Known limitations

• Intermarché can change these private endpoints or storage shapes without notice.
• Store selection is manual; there are no find_stores or set_store tools.
• One server instance operates one tab, one browser profile, and one active store.
• The login-status field is best-effort. The website is the authority on whether the session is authenticated.
• Headless operation is not a supported path.
• There is no checkout, order placement, payment, slot booking, or account-management tool.
• Only stdio transport is implemented.

License and attribution

MIT. See LICENSE for this project and NOTICE for the upstream mcp-leclerc-drive attribution and MIT license text.

Intermarché is a trademark of its respective owner. This project is unofficial and is not affiliated with or endorsed by Intermarché.