Carrefour Drive MCP — grocery shopping for your AI agent

MCP server for Carrefour Drive (carrefour.fr). Let Claude, Cursor, or any Model Context Protocol client search the French grocery catalogue, build a cart, pick a Drive pickup or delivery slot, read loyalty points and past receipts — on your own Carrefour account.

48 tools. 43 real carrefour.fr API endpoints described as JSON and run by a generic executor, plus 5 session-management tools. Adding an endpoint means dropping in a JSON file — no code.

"What did I buy last month?"            → get_loyalty_order_receipts
"Refill my usual weekly groceries."     → get_frequent_purchases + add_item_to_cart
"Cheapest organic pasta under 2 €?"     → search_products
"Book the Saturday morning Drive slot." → get_delivery_timeslots + select_cart_delivery_slot

• Standalone — no spectral binary, no external gateway, no API key. Clone, build, run.

• Cloudflare-proof — every call is issued from a real Chromium page, because nothing else gets a 200.

• Stays logged in — you log in once in a browser window; the server renews the session by itself through the OAuth2 SSO loop.

Table of contents

• Install

• Connect it to your agent — Claude Code · Claude Desktop · Cursor, Windsurf, Zed, VS Code

• Log in

• Tool reference

• Why a real browser

• How authentication works

• How the executor works

• Configuration

• Verify the install

• FAQ

Related MCP server: mcp-leclerc-drive

Install

Nothing to clone. Node.js 20+ is the only prerequisite (native fetch, FormData, node:test).

npx -y github:maximeallanic/CarrefourDriveMCP

That single command fetches, builds and starts the server on stdio — the first run also downloads the Chromium it uses as HTTP transport. Most of the time you never type it yourself: you put it in your MCP client config (next section) and the client runs it for you.

Prefer it installed once, globally?

npm install -g github:maximeallanic/CarrefourDriveMCP
carrefour-drive-mcp

Your session, browser profile and logs live in ~/.carrefour-drive-mcp ($XDG_DATA_HOME/carrefour-drive-mcp when set), so upgrades never log you out. Override with CARREFOUR_DATA_DIR.

git clone https://github.com/maximeallanic/CarrefourDriveMCP.git
cd CarrefourDriveMCP
npm install     # builds, and downloads the Chromium transport
node dist/index.js

A source checkout keeps its data in the repo's own data/ directory.

Connect it to your agent

Claude Code

claude mcp add carrefour-drive -- npx -y github:maximeallanic/CarrefourDriveMCP

Then, in any session:

> Log me in to Carrefour        (runs carrefour_browser_login)
> Add 2 L of semi-skimmed milk to my Drive cart

Claude Desktop

Edit claude_desktop_config.json:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

• Linux — ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "carrefour-drive": {
      "command": "npx",
      "args": ["-y", "github:maximeallanic/CarrefourDriveMCP"]
    }
  }
}

Restart Claude Desktop; the Carrefour tools appear in the tools menu.

On Windows, use "command": "cmd" with "args": ["/c", "npx", "-y", "github:maximeallanic/CarrefourDriveMCP"].

Cursor, Windsurf, Zed, VS Code and other MCP clients

Any client that speaks MCP over stdio takes the same two fields:

{
  "command": "npx",
  "args": ["-y", "github:maximeallanic/CarrefourDriveMCP"]
}

• Cursor — ~/.cursor/mcp.json (or .cursor/mcp.json in a project)

• Windsurf — ~/.codeium/windsurf/mcp_config.json

• VS Code / Copilot — .vscode/mcp.json, under "servers"

• Zed — settings.json, under "context_servers"

Installed globally or cloned instead? Swap in {"command": "carrefour-drive-mcp"} or {"command": "node", "args": ["/absolute/path/to/dist/index.js"]}.

Already have cookies? Pass them in an "env" block instead of logging in: {"CARREFOUR_COOKIES": "…cookie header…"}.

Log in

carrefour.fr signs you in with cookies, behind a Cloudflare Turnstile captcha and an OTP. So the login is interactive, once:

1. Ask your agent to run carrefour_browser_login.

2. A browser window opens on the Carrefour login page. Type your email, password and the OTP code yourself.

3. Don't close the window — the server detects the end of the OAuth loop, grabs the session cookies from memory and closes it for you.

From then on the session renews itself silently: the server replays the SSO authorize → callback redirect before authenticated calls, after a 401/403, and every 30 minutes as a keep-alive. You only log in again when the SSO cookie itself expires (24 h max, or 60 min idle) — the tools say so explicitly.

Check the state at any time with carrefour_session_status (verify: true makes a real call).

For carrefour_set_cookies, only the JSON array format carries the cookie domain — it's the only one that can supply c4iamsecuretk, without which automatic renewal is impossible.

The cookie jar lives in <data dir>/sessions/cookies.json (0600) and is re-injected into the browser profile on every start.

Tool reference

Search & catalogue (no account needed)

Cart & checkout

⚠️ submit_checkout_payment charges a real payment. Four of its parameters were captured as query string while their description suggests HTTP headers — check against a real trace before using it in production.

Account, orders & loyalty

Shopping lists

Why a real browser

carrefour.fr sits behind a Cloudflare managed challenge that fingerprints the client. Measured from one IP, on the same day:

No amount of header tweaking changes that: the only viable transport is a browser. And the requests must be issued from a page — Playwright's APIRequestContext uses a Node HTTP stack and gets blocked like fetch.

So the server keeps a persistent Chromium and runs every API call as a fetch inside a page parked on the target origin (one page per origin, because of CORS). It runs windowless, but not in standard headless mode:

The last line is what ships.

How authentication works

Two distinct cookie systems:

Login is interactive because of two constraints: the form is behind a Cloudflare Turnstile captcha that refuses to validate in a CDP-driven browser, and c4iamsecuretk is a session cookie Chromium never writes to disk. So the window is a plain Chromium with a debug port open but nothing attached until login finishes; the server polls the tab over plain HTTP on /json/list (no CDP domain enabled, so no automation trace), attaches the moment the OAuth loop lands back on the store, and reads the cookies from memory.

Renewal afterwards is a plain navigation — Chromium follows the redirects and sets the cookies itself:

GET moncompte.carrefour.fr/iam/oauth2/CarrefourConnect/authorize?client_id=…&redirect_uri=https://www.carrefour.fr/login/check
  └─302─► www.carrefour.fr/login/check?code=…   (the BFF exchanges the code)
      └─302─► www.carrefour.fr/                  (fresh session cookies)

How the executor works

tools/*.json ──► loader (validation) ──► params (JSON Schema ➜ zod) ──► MCP tools/list
                                     └─► resolve ($param ➜ URL/query/headers/body)
                                              └─► http.service (cookies + rate limit + fetch)

Every file in tools/ is self-describing:

{
  "name": "add_item_to_cart",
  "parameters": { "type": "object", "properties": { … }, "required": [ … ] },
  "request": {
    "method": "PATCH",
    "url": "https://www.carrefour.fr/api/cart",
    "headers": { … },
    "query": {},
    "body": { "items": [ { "ean": { "$param": "ean" }, … } ] },
    "content_type": "application/json"
  },
  "requires_auth": true
}

The engine (src/spec/):

• recursively substitutes {"$param": "name"} nodes in headers, query and body, preserving the original type (number, boolean, array);

• drops placeholders with no argument, so optional params vanish from the request instead of being sent as null;

• fills URL segments {basket_service_type}, {store_id}, … with encoding, failing with a clear message when a required segment is missing;

• serialises arrays as repeated query keys (codes[]=14&codes[]=15);

• encodes the body per content_type: JSON, x-www-form-urlencoded or multipart/form-data (boundary left to fetch);

• applies a sliding rate limit with jitter, plus browser headers.

Adding an endpoint = dropping a new JSON file into tools/. No code to write.

Configuration

See .env.example. Main variables:

Verify the install

From a source checkout:

npm run build     # tsc
npm test          # build + unit tests (node:test)
npm run smoke     # build + real MCP stdio handshake + tools/list
npm run verify    # all three

Tests cover $param substitution, URL segments, arrays in query strings, the three body encodings, and cookie-jar handling. The smoke test actually boots the server, performs the JSON-RPC handshake and lists the tools.

Network calls to carrefour.fr are not tested automatically — they need a real account and valid cookies.

FAQ

Do I need an API key? No. Carrefour has no public API; this server drives the same private endpoints the website uses, with your own session.

Does it work outside France? The catalogue and stores are French (carrefour.fr). Cloudflare may be stricter from some IPs.

Is my password stored? No. You type it in a browser window; only cookies are persisted, in ~/.carrefour-drive-mcp/sessions/cookies.json with 0600 permissions. No credential lives in this repo, and data/ and .env are gitignored.

Can it place a real order? Yes — submit_checkout_payment charges a real payment. Treat it accordingly.

Can I add endpoints? Drop a JSON file in tools/. See How the executor works.

Which clients are supported? Anything speaking MCP over stdio: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code / Copilot, Zed, Continue, custom agents using the MCP SDK.

Disclaimer

Unofficial project, not affiliated with, endorsed by, or supported by Carrefour. For personal and educational use on your own account. Respect Carrefour's terms of service and rate-limit yourself accordingly.

License

MIT © Maxime Allanic

Keywords: Carrefour MCP server · Carrefour Drive API · Model Context Protocol grocery · Claude Desktop MCP · Claude Code MCP server · Cursor MCP · French grocery shopping AI agent · courses en ligne · drive · liste de courses · fidélité Carrefour · MCP shopping cart automation.