Carrefour Drive MCP — Lebensmitteleinkauf für Ihren KI-Agenten

MCP-Server für Carrefour Drive (carrefour.fr). Lassen Sie Claude, Cursor oder einen beliebigen anderen Model Context Protocol-Client den französischen Lebensmittelkatalog durchsuchen, einen Warenkorb aufbauen, einen Drive-Abhol- oder Lieferslot wählen, Treuepunkte und frühere Belege lesen – auf Ihrem eigenen Carrefour-Konto.

48 Tools. 43 echte carrefour.fr-API-Endpunkte, die als JSON beschrieben und von einem generischen Ausführer ausgeführt werden, plus 5 Sitzungsverwaltungstools. Einen Endpunkt hinzuzufügen bedeutet, eine JSON-Datei einzufügen – ganz ohne 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

• Eigenständig – kein spectral-Binär, kein externes Gateway, kein API-Schlüssel. Klonen, bauen, ausführen.

• Cloudflare-fest – jeder Aufruf wird von einer echten Chromium-Seite ausgesendet, denn nichts anderes bekommt eine 200.

• Bleibt angemeldet – Sie melden sich einmal in einem Browserfenster an; der Server erneuert die Sitzung von selbst durch die OAuth2-SSO-Schleife.

Inhaltsverzeichnis

• Installation

• Verbinden Sie es mit Ihrem Agenten – Claude Code · Claude Desktop · Cursor, Windsurf, Zed, VS Code

• Anmelden

• Tool-Referenz

• Warum ein echter Browser

• Wie die Authentifizierung funktioniert

• Wie der Ausführer funktioniert

• Konfiguration

• Installation überprüfen

• FAQ

Related MCP server: mcp-leclerc-drive

Installation

Nichts zu klonen. Node.js 20+ ist die einzige Voraussetzung (native fetch, FormData, node:test).

npx -y github:maximeallanic/CarrefourDriveMCP

Dieser einzelne Befehl holt, baut und startet den Server auf stdio – beim ersten Ausführen wird auch das Chromium heruntergeladen, das er als HTTP-Transport verwendet. Meist müssen Sie den Befehl nie selbst tippen: Sie fügen ihn in die Konfiguration Ihres MCP-Clients ein (nächster Abschnitt) und der Client führt ihn für Sie aus.

Bevorzugt einmalig global installiert?

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

Ihre Sitzung, Ihr Browserprofil und Ihre Protokolle liegen in ~/.carrefour-drive-mcp ($XDG_DATA_HOME/carrefour-drive-mcp, wenn gesetzt), sodass Upgrades Sie nie abmelden. Überschreiben Sie dies mit 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

Ein Quelltext-Checkout behält seine Daten im eigenen data/-Verzeichnis des Repositorys.

Verbinden Sie es mit Ihrem Agenten

Claude Code

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

Dann, in jeder Sitzung:

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

Claude Desktop

Bearbeiten Sie 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"]
    }
  }
}

Starten Sie Claude Desktop neu; die Carrefour-Tools erscheinen im Tool-Menü.

Unter Windows verwenden Sie "command": "cmd" mit "args": ["/c", "npx", "-y", "github:maximeallanic/CarrefourDriveMCP"].

Cursor, Windsurf, Zed, VS Code und andere MCP-Clients

Jeder Client, der MCP über stdio spricht, akzeptiert dieselben zwei Felder:

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

• Cursor: – ~/.cursor/mcp.json (oder .cursor/mcp.json in einem Projekt)

• Windsurf: – ~/.codeium/windsurf/mcp_config.json

• VS Code / Copilot: – .vscode/mcp.json, unter "servers"

• Zed: – settings.json, unter "context_servers"

Global installiert oder geklont? Stattdessen tauschen Sie {"command": "carrefour-drive-mcp"} oder {"command": "node", "args": ["/absoluter/pfad/zu/dist/index.js"]} ein.

Haben Sie bereits Cookies? Übergeben Sie sie in einem "env"-Block anstelle der Anmeldung: {"CARREFOUR_COOKIES": "…Cookie-Header…"}.

Anmelden

carrefour.fr meldet Sie mit Cookies an, hinter einem Cloudflare-Turnstile-CAPTCHA und einem OTP. Die Anmeldung ist also einmalig interaktiv:

1. Bitten Sie Ihren Agenten, carrefour_browser_login auszuführen.

2. Ein Browserfenster öffnet sich auf der Carrefour-Anmeldeseite. Geben Sie selbst Ihre E-Mail-Adresse, Ihr PasswortTel. und den OTP-Code ein.

3. Schließen Sie das Fenster nicht – der Server erkennt das Ende der OAuth-Schleife, übernimmt die Sitzungs-Cookies aus dem Speicher und schließt es dann von selbst.

Ab dann erneuert sich die Sitzung still und leise: Den Server wiederspielt die SSO-Autorisierung → Callback-Umleitung vor authentifizierten Aufrufen, nach einem 401/403 und alle 30 Minuten als Keep-Alive. Sie melden sich nur wieder an, wenn das SSO-Cookie selbst abläuft (max. 24 Std., oder 60 Min. ohne Aktivität) – die Tools sagen dies explizit.

Überprüfen Sie den Status jederzeit mit carrefour_session_status (verify: true macht einen echten Aufruf).

Für carrefour_set_cookies trägt nur das JSON-Array-Format die Cookie-Domäne, – es ist das einzige, das c4iamsecuretk liefern kann, ohne das eine automatische Verlängerung unmöglich ist.

Der Cookie-Topf lebt in <data dir>/sessions/cookies.json (0600) und wird bei jedem Start in das Browserprofil neu injiziert.

Tool-Referenz

Suche & Katalog (kein Konto nötig)

Warenkorb & Checkout

⚠️ submit_checkout_payment verlangt eine echte Zahlung. Vier seiner Parameter wurden als Anfragezeichen-Zeichenzeichenkette erfasst, während ihre Beschreibung über HTTP-Header vermuten lässt – überprüfen Sie dies gegen eine echte Ablaufspur, bevor Sie es in Produktion verwenden.

Konto, Bestellungen & Treueprogramm

Einkaufslisten

Warum ein echter Browser

carrefour.fr liegt hinter einer Cloudflare managed challenge, die den Client per Fingerprint identifiziert. Gemessen von einer IP aus, am selben Tag:

Kein noch so großes Herumtüfteln an Headern ändert das: Der einzige gangbare Transport ist ein Browser. Und die Anfragen müssen von einer Seite aus erfolgen – Playwrights APIRequestContext verwendet einen Node-HTTP-Stack und wird wie fetch blockiert.

Der Server hält also ein persistentes Chromium und führt jeden API-Aufruf als fetch innerhalb einer Seite aus, die auf der Ziel-Origin geparkt ist (eine Seite pro Origin, wegen CORS). Er läuft fensterlos, aber nicht im Standard-Headless-Modus:

Die letzte Zeile ist das, was ausgeliefert wird.

Wie die Authentifizierung funktioniert

Zwei getrennte Cookie-Systeme:

Der Login ist interaktiv, weil zwei Einschränkungen bestehen: Das Formular liegt hinter einem Cloudflare Turnstile-Captcha, das sich in einem CDP-gesteuerten Browser nicht validieren lässt, und c4iamsecuretk ist ein Session-Cookie, das Chromium nie auf die Festplatte schreibt. Das Fenster ist daher ein normales Chromium mit offenem Debug-Port, aber nichts ist angehängt, bis der Login abgeschlossen ist; der Server pollt die Tab über einfaches HTTP auf /json/list (keine CDP-Domain aktiviert, daher keine Automatisierungsspur), hängt sich an, sobald die OAuth-Schleife wieder auf dem Shop landet, und liest die Cookies aus dem Speicher.

Die Erneuerung danach ist eine einfache Navigation – Chromium folgt den Weiterleitungen und setzt die Cookies selbst:

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)

So funktioniert der Executor

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

Jede Datei in tools/ ist selbstbeschreibend:

{
  "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
}

Die Engine (src/spec/):

• ersetzt rekursiv {"$param": "name"}-Knoten in headers, query und body, wobei der ursprüngliche Typ (Zahl, Boolean, Array) erhalten bleibt;

• verwirft Platzhalter ohne Argument, sodass optionale Parameter aus der Anfrage verschwinden, statt als null gesendet zu werden;

• füllt URL-Segmente {basket_service_type}, {store_id}, … mit Kodierung und schlägt mit einer klaren Meldung fehl, wenn ein erforderliches Segment fehlt;

• serialisiert Arrays als wiederholte Query-Schlüssel (codes[]=14&codes[]=15);

• kodiert den Body gemäß content_type: JSON, x-www-form-urlencoded oder multipart/form-data (Boundary bleibt fetch überlassen);

• wendet ein gleitendes Rate-Limit mit Jitter an, plus Browser-Header.

Einen Endpunkt hinzuzufügen = eine neue JSON-Datei in tools/ ablegen. Kein Code zu schreiben.

Konfiguration

Siehe .env.example. Hauptvariablen:

Installation überprüfen

Aus einem Quellcode-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

Die Tests decken die $param-Substitution, URL-Segmente, Arrays in Query-Strings, die drei Body-Kodierungen und die Cookie-Jar-Verwaltung ab. Der Smoke-Test startet tatsächlich den Server, führt den JSON-RPC-Handshake durch und listet die Tools auf.

Netzwerkaufrufe an carrefour.fr werden nicht automatisiert getestet – sie benötigen ein echtes Konto und gültige Cookies.

FAQ

Brauche ich einen API-Schlüssel? Nein. Carrefour hat keine öffentliche API; dieser Server nutzt dieselben privaten Endpunkte wie die Website, mit deiner eigenen Sitzung.

Funktioniert es außerhalb Frankreichs? Der Katalog und die Filialen sind französisch (carrefour.fr). Cloudflare kann von manchen IPs aus strenger sein.

Wird mein Passwort gespeichert? Nein. Du gibst es in einem Browserfenster ein; nur Cookies werden gespeichert, in ~/.carrefour-drive-mcp/sessions/cookies.json mit 0600-Berechtigungen. Keine Zugangsdaten liegen in diesem Repo, und data/ und .env sind gitignored.

Kann es eine echte Bestellung aufgeben? Ja – submit_checkout_payment belastet eine echte Zahlung. Behandle es entsprechend.

Kann ich Endpunkte hinzufügen? Lege eine JSON-Datei in tools/ ab. Siehe So funktioniert der Executor.

Welche Clients werden unterstützt? Alles, was MCP über stdio spricht: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code / Copilot, Zed, Continue, benutzerdefinierte Agenten, die das MCP SDK verwenden.

Haftungsausschluss

Inoffizielles Projekt, nicht mit Carrefour verbunden, von Carrefour unterstützt oder befürwortet. Für den persönlichen und pädagogischen Gebrauch auf deinem eigenen Konto. Respektiere die Nutzungsbedingungen von Carrefour und begrenze deine Anfragen entsprechend.

Lizenz

MIT © Maxime Allanic

Keywords: Carrefour MCP server · Carrefour Drive API · Model Context Protocol Lebensmittel · Claude Desktop MCP · Claude Code MCP server · Cursor MCP · Französischer KI-Agent für Lebensmitteleinkauf · courses en ligne · drive · liste de courses · fidélité Carrefour · MCP Warenkorb-Automatisierung.