Carrefour Drive MCP — compra de supermercado para tu agente de IA

Servidor MCP para Carrefour Drive (carrefour.fr). Permite que Claude, Cursor o cualquier cliente del Model Context Protocol busque en el catálogo de supermercado francés, cree una cesta, elija una franja de recogida en Drive o de entrega, consulte los puntos de fidelidad y los recibos anteriores, con tu propia cuenta de Carrefour.

48 herramientas. 43 endpoints reales de la API de carrefour.fr descritos como JSON y ejecutados por un ejecutor genérico, más 5 herramientas de gestión de sesión. Añadir un endpoint significa añadir un archivo JSON, sin código.

"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

• Independiente — sin binario spectral, sin pasarela externa, sin clave de API. Clona, compila, ejecuta.

• A prueba de Cloudflare — cada llamada se realiza desde una página Chromium real, porque nada más obtiene un 200.

• Mantiene la sesión iniciada — inicias sesión una vez en una ventana del navegador; el servidor renueva la sesión por sí mismo mediante el bucle SSO de OAuth2.

Índice

• Instalación

• Conéctalo a tu agente — Claude Code · Claude Desktop · Cursor, Windsurf, Zed, VS Code

• Iniciar sesión

• Referencia de herramientas

• Por qué un navegador real

• Cómo funciona la autenticación

• Cómo funciona el ejecutor

• Configuración

• Verificar la instalación

• Preguntas frecuentes

Related MCP server: mcp-leclerc-drive

Instalación

No hay nada que clonar. Node.js 20+ es el único requisito (fetch, FormData y node:test nativos).

npx -y github:maximeallanic/CarrefourDriveMCP

Ese único comando descarga, compila e inicia el servidor en stdio; la primera ejecución también descarga el Chromium que usa como transporte HTTP. La mayoría de las veces no lo escribes tú: lo pones en la configuración de tu cliente MCP (siguiente sección) y el cliente lo ejecuta por ti.

¿Prefieres instalarlo una sola vez, de forma global?

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

Tu sesión, perfil de navegador y registros viven en ~/.carrefour-drive-mcp ($XDG_DATA_HOME/carrefour-drive-mcp si está definido), así que las actualizaciones nunca te cierran la sesión. Anula con 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

Una copia del código fuente guarda sus datos en el directorio data/ del propio repositorio.

Conéctalo a tu agente

Claude Code

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

Luego, en cualquier sesión:

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

Claude Desktop

Edita 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"]
    }
  }
}

Reinicia Claude Desktop; las herramientas de Carrefour aparecen en el menú de herramientas.

En Windows, usa "command": "cmd" con "args": ["/c", "npx", "-y", "github:maximeallanic/CarrefourDriveMCP"].

Cursor, Windsurf, Zed, VS Code y otros clientes MCP

Cualquier cliente que hable MCP sobre stdio acepta los mismos dos campos:

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

• Cursor — ~/.cursor/mcp.json (o .cursor/mcp.json en un proyecto)

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

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

• Zed — settings.json, bajo "context_servers"

¿Instalado globalmente o clonado? Sustituye por {"command": "carrefour-drive-mcp"} o {"command": "node", "args": ["/absolute/path/to/dist/index.js"]}.

¿Ya tienes cookies? Pásalas en un bloque "env" en lugar de iniciar sesión: {"CARREFOUR_COOKIES": "…cookie header…"}.

Iniciar sesión

carrefour.fr te identifica con cookies, detrás de un captcha de Cloudflare Turnstile y un OTP. Por eso el inicio de sesión es interactivo, una sola vez:

1. Pide a tu agente que ejecute carrefour_browser_login.

2. Se abre una ventana del navegador en la página de inicio de sesión de Carrefour. Escribe tú mismo tu correo electrónico, contraseña y el código OTP.

3. No cierres la ventana — el servidor detecta el final del bucle OAuth, captura las cookies de sesión de la memoria y la cierra por ti.

A partir de entonces, la sesión se renueva sola silenciosamente: el servidor reproduce la redirección de autorización → callback del SSO antes de las llamadas autenticadas, después de un 401/403, y cada 30 minutos como keep-alive. Solo tienes que volver a iniciar sesión cuando la propia cookie SSO caduque (máx. 24 h, o 60 min de inactividad) — las herramientas lo indican explícitamente.

Comprueba el estado en cualquier momento con carrefour_session_status (verify: true hace una llamada real).

Para carrefour_set_cookies, solo el formato array JSON incluye el dominio de la cookie — es el único que puede proporcionar c4iamsecuretk, sin el cual la renovación automática es imposible.

El almacén de cookies vive en <data dir>/sessions/cookies.json (0600) y se reinyecta en el perfil del navegador en cada inicio.

Referencia de herramientas

Búsqueda y catálogo (sin necesidad de cuenta)

Cesta y pago

⚠️ submit_checkout_payment cobra un pago real. Cuatro de sus parámetros se capturaron como cadena de consulta mientras que su descripción sugiere cabeceras HTTP — compruébalo con un rastro real antes de usarlo en producción.

Cuenta, pedidos y fidelidad

Listas de la compra

Por qué un navegador real

carrefour.fr está detrás de un desafío gestionado de Cloudflare que toma la huella del cliente. Medido desde una IP, el mismo día:

Ninguna manipulación de cabeceras cambia eso: el único transporte viable es un navegador. Y las peticiones deben emitirse desde una página — el APIRequestContext de Playwright usa una pila HTTP de Node y se bloquea como fetch.

Así que el servidor mantiene un Chromium persistente y ejecuta cada llamada API como un fetch dentro de una página anclada en el origen de destino (una página por origen, por CORS). Se ejecuta sin ventana, pero no en modo headless estándar:

La última línea es la que se distribuye.

Cómo funciona la autenticación

Dos sistemas de cookies distintos:

El inicio de sesión es interactivo por dos restricciones: el formulario está detrás de un captcha Cloudflare Turnstile que se niega a validar en un navegador controlado por CDP, y c4iamsecuretk es una cookie de sesión que Chromium nunca escribe en disco. Así que la ventana es un Chromium normal con un puerto de depuración abierto pero nada conectado hasta que el inicio de sesión termina; el servidor consulta la pestaña por HTTP normal en /json/list (sin dominio CDP habilitado, así que no hay rastro de automatización), se conecta en el momento en que el bucle OAuth vuelve a la tienda, y lee las cookies de la memoria.

La renovación posterior es una navegación normal: Chromium sigue las redirecciones y establece las cookies por sí mismo:

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)

Cómo funciona el ejecutor

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

Cada archivo en tools/ se autodescribe:

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

El motor (src/spec/):

• sustituye recursivamente los nodos {"$param": "name"} en headers, query y body, conservando el tipo original (número, booleano, array);

• elimina los placeholders sin argumento, de modo que los parámetros opcionales desaparecen de la petición en lugar de enviarse como null;

• rellena los segmentos de URL {basket_service_type}, {store_id}, … con codificación, fallando con un mensaje claro cuando falta un segmento obligatorio;

• serializa los arrays como claves de consulta repetidas (codes[]=14&codes[]=15);

• codifica el cuerpo según content_type: JSON, x-www-form-urlencoded o multipart/form-data (el boundary se deja a fetch);

• aplica un límite de tasa deslizante con jitter, además de cabeceras de navegador.

Añadir un endpoint = colocar un nuevo archivo JSON en tools/. Sin código que escribir.

Configuración

Ver .env.example. Variables principales:

Verificar la instalación

Desde una copia del código fuente:

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

Las pruebas cubren la sustitución de $param, los segmentos de URL, los arrays en cadenas de consulta, las tres codificaciones de cuerpo y el manejo del almacén de cookies. La prueba de humo arranca el servidor, realiza el handshake JSON-RPC y lista las herramientas.

Las llamadas de red a carrefour.fr no se prueban automáticamente: necesitan una cuenta real y cookies válidas.

Preguntas frecuentes

¿Necesito una clave API? No. Carrefour no tiene API pública; este servidor usa los mismos endpoints privados que el sitio web, con tu propia sesión.

¿Funciona fuera de Francia? El catálogo y las tiendas son franceses (carrefour.fr). Cloudflare puede ser más estricto desde algunas IPs.

¿Se guarda mi contraseña? No. La escribes en una ventana del navegador; solo se persisten cookies, en ~/.carrefour-drive-mcp/sessions/cookies.json con permisos 0600. Ninguna credencial vive en este repositorio, y data/ y .env están en gitignore.

¿Puede hacer un pedido real? Sí — submit_checkout_payment cobra un pago real. Trátalo en consecuencia.

¿Puedo añadir endpoints? Coloca un archivo JSON en tools/. Ver Cómo funciona el ejecutor.

¿Qué clientes se admiten? Cualquier cosa que hable MCP sobre stdio: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code / Copilot, Zed, Continue, agentes personalizados que usen el MCP SDK.

Descargo de responsabilidad

Proyecto no oficial, no afiliado, respaldado ni soportado por Carrefour. Para uso personal y educativo en tu propia cuenta. Respeta los términos de servicio de Carrefour y limita tu tasa en consecuencia.

Licencia

MIT © Maxime Allanic

Palabras clave: Carrefour MCP server · Carrefour Drive API · Model Context Protocol de supermercado · Claude Desktop MCP · Claude Code MCP server · Cursor MCP · agente de IA para compras de supermercado en Francia · compras en línea · drive · lista de la compra · fidelidad Carrefour · automatización del carrito de la compra MCP.