MCP-сервер Carrefour Drive — покупка продуктов для вашего ИИ-агента

MCP-сервер для Carrefour Drive (carrefour.fr). Позвольте Claude, Cursor или любому клиенту Model Context Protocol искать товары во французском каталоге, собирать корзину, выбирать слот самовывоза Drive или доставки, просматривать бонусные баллы и прошлые чеки — на вашем собственном аккаунте Carrefour.

48 инструментов. 43 реальных API-эндпоинта carrefour.fr, описанных в JSON и выполняемых универсальным исполнителем, плюс 5 инструментов управления сессией. Добавить эндпоинт — значит добавить JSON-файл, без единой строки кода.

"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

• Автономный — без бинарника spectral, без внешнего шлюза, без API-ключа. Клонируйте, собирайте, запускайте.

• Устойчив к Cloudflare — каждый запрос выполняется из реальной страницы Chromium, потому что ничто другое не получает 200.

• Остаётся в системе — вы входите один раз в окне браузера; сервер сам продлевает сессию через цикл OAuth2 SSO.

Содержание

• Установка

• Подключение к агенту — Claude Code · Claude Desktop · Cursor, Windsurf, Zed, VS Code

• Вход в систему

• Справочник инструментов

• Зачем нужен реальный браузер

• Как работает аутентификация

• Как работает исполнитель

• Конфигурация

• Проверка установки

• FAQ

Related MCP server: mcp-leclerc-drive

Установка

Клонировать ничего не нужно. Единственное требование — Node.js 20+ (нативные fetch, FormData, node:test).

npx -y github:maximeallanic/CarrefourDriveMCP

Эта единственная команда загружает, собирает и запускает сервер на stdio — при первом запуске также скачивается Chromium, используемый в качестве HTTP-транспорта. В большинстве случаев вам не придётся вводить её вручную: вы помещаете её в конфиг вашего MCP-клиента (следующий раздел), и клиент запускает её за вас.

Предпочитаете установить один раз, глобально?

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

Ваша сессия, профиль браузера и журналы хранятся в ~/.carrefour-drive-mcp ($XDG_DATA_HOME/carrefour-drive-mcp, если задано), поэтому обновления не разлогинивают вас. Переопределяется через 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

Копия из исходников хранит свои данные в собственной директории data/ репозитория.

Подключение к агенту

Claude Code

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

Затем в любой сессии:

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

Claude Desktop

Отредактируйте 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"]
    }
  }
}

Перезапустите Claude Desktop; инструменты Carrefour появятся в меню инструментов.

В Windows используйте "command": "cmd" с "args": ["/c", "npx", "-y", "github:maximeallanic/CarrefourDriveMCP"].

Cursor, Windsurf, Zed, VS Code и другие MCP-клиенты

Любой клиент, поддерживающий MCP через stdio, принимает те же два поля:

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

• Cursor — ~/.cursor/mcp.json (или .cursor/mcp.json в проекте)

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

• VS Code / Copilot — .vscode/mcp.json, в разделе "servers"

• Zed — settings.json, в разделе "context_servers"

Установлено глобально или клонировано? Вместо этого подставьте {"command": "carrefour-drive-mcp"} или {"command": "node", "args": ["/absolute/path/to/dist/index.js"]}.

Уже есть куки? Передайте их в блоке "env" вместо входа в систему: {"CARREFOUR_COOKIES": "…cookie header…"}.

Вход в систему

carrefour.fr выполняет вход с помощью куки, за Cloudflare Turnstile-капчей и OTP-кодом. Поэтому вход интерактивный, один раз:

1. Попросите агента выполнить carrefour_browser_login.

2. Откроется окно браузера со страницей входа Carrefour. Введите адрес электронной почты, пароль и OTP-код самостоятельно.

3. Не закрывайте окно — сервер обнаружит завершение цикла OAuth, заберёт куки сессии из памяти и закроет его за вас.

После этого сессия продлевается сама, незаметно: сервер воспроизводит редирект authorize → callback SSO перед аутентифицированными вызовами, после 401/403, и каждые 30 минут в качестве keep-alive. Повторный вход нужен только когда истекает сама SSO-кука (максимум 24 часа, или 60 минут простоя) — инструменты сообщают об этом явно.

Проверьте состояние в любой момент с помощью carrefour_session_status (verify: true выполняет реальный запрос).

Для carrefour_set_cookies только JSON-массив несёт домен куки — только он может предоставить c4iamsecuretk, без которого автоматическое продление невозможно.

Хранилище куки находится в <data dir>/sessions/cookies.json (0600) и повторно внедряется в профиль браузера при каждом запуске.

Справочник инструментов

Поиск и каталог (аккаунт не требуется)

Корзина и оформление заказа

⚠️ submit_checkout_payment списывает реальный платёж. Четыре его параметра были перехвачены в строке запроса, хотя их описание предполагает HTTP-заголовки — сверьтесь с реальным трафиком перед использованием в продакшене.

Аккаунт, заказы и лояльность

Списки покупок

Зачем нужен настоящий браузер

carrefour.fr находится за Cloudflare managed challenge, который снимает отпечаток клиента. Замеры с одного IP-адреса в один и тот же день:

Никакие подстройки заголовков этого не меняют: единственный рабочий транспорт — браузер. И запросы должны отправляться со страницы — APIRequestContext из Playwright использует HTTP-стек Node.js и блокируется так же, как fetch.

Поэтому сервер держит постоянный Chromium и выполняет каждый API-вызов как fetch внутри страницы, размещённой на целевом origin (по одной странице на origin из-за CORS). Он работает без окна, но не в стандартном headless-режиме:

В сборку идёт именно последняя строка.

Как работает аутентификация

Две отдельные cookie-системы:

Вход в систему интерактивен из-за двух ограничений: форма защищена капчей Cloudflare Turnstile, которая отказывается проходить проверку в браузере под управлением CDP, а c4iamsecuretk — это сессионный cookie, который Chromium никогда не записывает на диск. Поэтому окно — это обычный Chromium с открытым debug-портом, но ничего не подключено, пока вход не завершён; сервер опрашивает вкладку по обычному HTTP на /json/list (ни один CDP-домен не включён, поэтому следов автоматизации нет), подключается в тот момент, когда OAuth-цикл возвращается на сайт магазина, и читает cookie из памяти.

Последующее обновление — это обычная навигация: Chromium сам следует за редиректами и устанавливает cookie:

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)

Как работает исполнитель

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

Каждый файл в tools/ самодокументируемый:

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

Движок (src/spec/):

• рекурсивно подставляет узлы {"$param": "name"} в headers, query и body, сохраняя исходный тип (число, логическое значение, массив);

• отбрасывает плейсхолдеры без аргумента, так что необязательные параметры исчезают из запроса, а не отправляются как null;

• заполняет сегменты URL {basket_service_type}, {store_id}, … с кодированием, выдавая понятное сообщение об ошибке, если обязательный сегмент отсутствует;

• сериализует массивы как повторяющиеся ключи запроса (codes[]=14&codes[]=15);

• кодирует тело согласно content_type: JSON, x-www-form-urlencoded или multipart/form-data (boundary оставляется на fetch);

• применяет скользящее ограничение частоты с джиттером, а также заголовки браузера.

Добавление эндпоинта = добавление нового JSON-файла в tools/. Писать код не нужно.

Конфигурация

Смотрите .env.example. Основные переменные:

Проверка установки

Из рабочей копии исходников:

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

Тесты покрывают подстановку $param, сегменты URL, массивы в строке запроса, три кодировки тела и работу с cookie-jar. Смоук-тест реально запускает сервер, выполняет JSON-RPC handshake и выводит список инструментов.

Сетевые вызовы к carrefour.fr не тестируются автоматически — для них нужен реальный аккаунт и валидные cookie.

Часто задаваемые вопросы

Нужен ли мне API-ключ? Нет. У Carrefour нет публичного API; этот сервер использует те же приватные эндпоинты, что и веб-сайт, с вашей собственной сессией.

Работает ли это за пределами Франции? Каталог и магазины французские (carrefour.fr). Cloudflare может быть строже с некоторых IP-адресов.

Сохраняется ли мой пароль? Нет. Вы вводите его в окне браузера; сохраняются только cookie, в ~/.carrefour-drive-mcp/sessions/cookies.json с правами 0600. Никакие учётные данные в этом репозитории не хранятся, а data/ и .env игнорируются git.

Может ли он разместить настоящий заказ? Да — submit_checkout_payment списывает реальный платёж. Относитесь к этому соответственно.

Могу ли я добавлять эндпоинты? Положите JSON-файл в tools/. Смотрите Как работает исполнитель.

Какие клиенты поддерживаются? Всё, что говорит по MCP через stdio: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code / Copilot, Zed, Continue, пользовательские агенты на MCP SDK.

Отказ от ответственности

Неофициальный проект, не связан с Carrefour, не одобрен и не поддерживается Carrefour. Для личного и образовательного использования на вашем собственном аккаунте. Соблюдайте условия обслуживания Carrefour и самостоятельно ограничивайте частоту запросов.

Лицензия

MIT © Maxime Allanic

Ключевые слова: Carrefour MCP server · Carrefour Drive API · Model Context Protocol продукты · Claude Desktop MCP · Claude Code MCP server · Cursor MCP · французский ИИ-агент для покупки продуктов · courses en ligne · drive · liste de courses · fidélité Carrefour · автоматизация корзины покупок MCP.