Carrefour Drive MCP — AI 에이전트를 위한 식료품 쇼핑

Carrefour Drive(carrefour.fr)용 MCP 서버. Claude, Cursor 또는 어떤 Model Context Protocol 클라이언트든 프랑스 식료품 카탈로그를 검색하고, 장바구니를 구성하고, Drive 픽업 또는 배송 슬롯을 선택하고, 로열티 포인트와 과거 영수증을 읽을 수 있습니다 — 자신의 Carrefour 계정으로.

48개의 도구. 43개의 실제 carrefour.fr API 엔드포인트가 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에서 시작합니다. 첫 실행 시 HTTP 전송으로 사용하는 Chromium도 다운로드합니다. 대부분의 경우 직접 입력할 필요가 없습니다. 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 클라이언트

stdio를 통해 MCP를 지원하는 모든 클라이언트는 동일한 두 필드를 사용합니다:

{
  "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 루프의 종료를 감지하고 세션 쿠키를 메모리에서 가져와 창을 닫아줍니다.

이후 세션은 자동으로 조용히 갱신됩니다. 서버는 인증된 호출 전, 401/403 후, 그리고 30분마다 keep-alive로 SSO authorize → callback 리디렉션을 재생합니다. 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 관리형 챌린지 뒤에 있습니다. 동일한 IP에서 같은 날 측정한 결과:

헤더를 아무리 조정해도 달라지지 않습니다. 유일하게 가능한 전송 방식은 브라우저입니다. 그리고 요청은 페이지에서 실행되어야 합니다. Playwright의 APIRequestContext는 Node HTTP 스택을 사용하므로 fetch처럼 차단됩니다.

따라서 서버는 영구 Chromium을 유지하고 모든 API 호출을 대상 오리진에 머물러 있는 페이지 내부의 fetch로 실행합니다(CORS 때문에 오리진당 페이지 하나). 창 없는(windowless) 모드로 실행되지만 표준 headless 모드는 아닙니다:

마지막 줄이 실제 배포되는 방식입니다.

인증 작동 방식

두 가지 별개의 쿠키 시스템:

로그인은 두 가지 제약 때문에 대화형으로 이루어집니다: 폼이 Cloudflare Turnstile 캡차 뒤에 있어 CDP 기반 브라우저에서는 검증을 거부하고, c4iamsecuretk는 Chromium이 디스크에 절대 쓰지 않는 세션 쿠키이기 때문입니다. 따라서 창은 디버그 포트가 열려 있지만 로그인이 끝날 때까지 아무것도 연결되지 않은 일반 Chromium입니다. 서버는 /json/list에서 일반 HTTP로 탭을 폴링하고(CDP 도메인이 활성화되어 있지 않아 자동화 흔적이 없음), OAuth 루프가 매장으로 돌아오는 순간 연결하여 메모리에서 쿠키를 읽습니다.

이후 갱신은 일반 탐색입니다. Chromium이 리디렉션을 따라가며 쿠키를 직접 설정합니다:

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/):

• headers, query, body의 {"$param": "name"} 노드를 재귀적으로 대체하며 원래 타입(숫자, 불리언, 배열)을 유지합니다;

• 인자가 없는 플레이스홀더는 제거하여 선택적 매개변수가 null로 전송되는 대신 요청에서 사라지게 합니다;

• URL 세그먼트 {basket_service_type}, {store_id} 등을 인코딩하여 채우고, 필수 세그먼트가 없으면 명확한 메시지와 함께 실패합니다;

• 배열을 반복되는 쿼리 키(codes[]=14&codes[]=15)로 직렬화합니다;

• content_type에 따라 본문을 인코딩합니다: JSON, x-www-form-urlencoded 또는 multipart/form-data(boundary는 fetch에 맡김);

• 지터가 포함된 슬라이딩 속도 제한과 브라우저 헤더를 적용합니다.

엔드포인트 추가 = tools/에 새 JSON 파일을 넣는 것. 작성할 코드가 없습니다.

구성

.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 세그먼트, 쿼리 문자열의 배열, 세 가지 본문 인코딩, 쿠키 저장소 처리를 다룹니다. 스모크 테스트는 실제로 서버를 부팅하고 JSON-RPC 핸드셰이크를 수행하며 도구를 나열합니다.

carrefour.fr에 대한 네트워크 호출은 자동으로 테스트되지 않습니다. 실제 계정과 유효한 쿠키가 필요합니다.

FAQ

API 키가 필요한가요? 아니요. Carrefour에는 공개 API가 없습니다. 이 서버는 웹사이트가 사용하는 동일한 비공개 엔드포인트를 사용자의 세션으로 구동합니다.

프랑스 외부에서도 작동하나요? 카탈로그와 매장은 프랑스용입니다(carrefour.fr). 일부 IP에서는 Cloudflare가 더 엄격할 수 있습니다.

비밀번호가 저장되나요? 아니요. 브라우저 창에 직접 입력하며, 쿠키만 ~/.carrefour-drive-mcp/sessions/cookies.json에 0600 권한으로 저장됩니다. 이 저장소에는 자격 증명이 없으며 data/와 .env는 gitignore 처리됩니다.

실제 주문을 할 수 있나요? 네. submit_checkout_payment는 실제 결제를 청구합니다. 그에 따라 취급하세요.

엔드포인트를 추가할 수 있나요? tools/에 JSON 파일을 넣으세요. 실행기 작동 방식을 참조하세요.

지원되는 클라이언트는 무엇인가요? stdio를 통해 MCP를 사용하는 모든 것: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code / Copilot, Zed, Continue, MCP SDK를 사용하는 커스텀 에이전트.

면책 조항

비공식 프로젝트로, Carrefour와 제휴, 보증, 지원 관계가 없습니다. 본인 계정에서 개인적·교육적 용도로 사용하세요. Carrefour의 서비스 약관을 준수하고 그에 따라 속도 제한을 적용하세요.

라이선스

MIT © Maxime Allanic

키워드: Carrefour MCP 서버 · Carrefour Drive API · Model Context Protocol 식료품 · Claude Desktop MCP · Claude Code MCP 서버 · Cursor MCP · 프랑스 식료품 쇼핑 AI 에이전트 · courses en ligne · drive · liste de courses · fidélité Carrefour · MCP 장바구니 자동화.