Carrefour Drive MCP — 为你的 AI 代理提供生鲜杂货购物能力

适用于 Carrefour Drive（carrefour.fr）的 MCP 服务器。 让 Claude、Cursor 或任何 Model Context Protocol 客户端在你的 Carrefour 账户上搜索法国生鲜杂货目录、构建购物车、 选择 Drive 自提或配送时段、查看积分和过往收据。

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

• 登录

• 工具参考

• 为什么使用真实浏览器

• 身份验证如何工作

• 执行器如何工作

• 配置

• 验证安装

• 常见问题

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 时为 $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"]}。

已有 Cookie？在 "env" 块中传入即可，无需登录： {"CARREFOUR_COOKIES": "…cookie header…"}。

登录

carrefour.fr 通过 Cookie 登录，背后还有 Cloudflare Turnstile 验证码和 OTP。因此登录是交互式的，只需一次：

1. 让代理运行 carrefour_browser_login。

2. 浏览器窗口会在 Carrefour 登录页面上打开。请自行输入邮箱、密码 和 OTP 验证码。

3. 不要关闭窗口 — 服务器会检测 OAuth 循环的结束， 从内存中抓取会话 Cookie 并替你关闭窗口。

此后会话会自动静默续期：服务器会在经过身份验证的调用之前重放 SSO authorize → callback 重定向，在 401/403 之后也会如此， 并且每 30 分钟执行一次保活。只有当 SSO Cookie 本身过期时 （最长 24 小时，或空闲 60 分钟）你才需要重新登录——工具会明确提示。

随时用 carrefour_session_status 检查状态（verify: true 会发起 真实调用）。

对于 carrefour_set_cookies，只有 JSON 数组 格式携带 Cookie 域名——它是唯一能提供 c4iamsecuretk 的格式，没有它就无法 自动续期。

Cookie 存储位于 <data dir>/sessions/cookies.json（权限 0600）， 每次启动时都会重新注入浏览器配置文件。

工具参考

搜索与目录 (无需账户)

购物车与结算

⚠️ submit_checkout_payment 会发起真实扣款。它的四个参数 被捕获为查询字符串，而描述却暗示它们是 HTTP 头——在生产环境中使用前 请对照真实调用记录进行核实。

账户、订单与积分

购物清单

为什么需要真实浏览器

carrefour.fr 位于 Cloudflare managed challenge（托管质询）之后，会对客户端进行指纹识别。从同一 IP 在同一天测得的结果如下：

无论怎样调整请求头都无法改变这一点：唯一可行的传输方式是浏览器。而且请求必须从页面内发出——Playwright 的 APIRequestContext 使用的是 Node HTTP 栈，会像 fetch 一样被拦截。

因此，服务器保持一个常驻的 Chromium，并让每个 API 调用都以 fetch 的形式在停留于目标源（origin）的页面内执行（每个源一个页面，这是出于 CORS 的限制）。它以**无窗口（windowless）**模式运行，但不是标准的无头模式：

最后一行就是实际发布所用的方式。

身份验证的工作原理

两套不同的 Cookie 系统：

登录是交互式的，原因有两个限制：登录表单位于 Cloudflare Turnstile 验证码之后，而该验证码拒绝在 CDP 驱动的浏览器中通过验证；此外，c4iamsecuretk 是会话 Cookie，Chromium 永远不会将其写入磁盘。因此，窗口是一个普通的 Chromium，调试端口已打开，但在登录完成前不附加任何调试连接；服务器通过普通 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/）：

• 递归替换 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 段、查询字符串中的数组、三种请求体编码以及 cookie-jar 处理。冒烟测试会实际启动服务器，完成 JSON-RPC 握手并列出所有工具。

对 carrefour.fr 的网络调用不会自动测试——它们需要真实账号和有效的 Cookie。

常见问题

需要 API 密钥吗？ 不需要。Carrefour 没有公开 API；本服务器驱动的是网站所使用的同一批私有端点，用的是你自己的会话。

在法国之外能用吗？ 商品目录和门店都在法国（carrefour.fr）。对于某些 IP，Cloudflare 可能会采取更严格的策略。

密码会被存储吗？ 不会。你在浏览器窗口中输入密码；只有 Cookie 会被持久化，存储在 ~/.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 的认可或支持。仅供在个人账号上用于个人和教育用途。请遵守 Carrefour 的服务条款，并相应地限制自己的请求频率。

许可证

MIT © Maxime Allanic

关键词：Carrefour MCP server · Carrefour Drive API · Model Context Protocol 杂货 · Claude Desktop MCP · Claude Code MCP server · Cursor MCP · 法国食品杂货购物AI代理 · courses en ligne · drive · liste de courses · fidélité Carrefour · MCP 购物车自动化。