leclerc-drive

mcp-leclerc-drive

E.Leclerc Drive 向け初のオープンソース MCP サーバーです。Claude がウェブサイトをクリックして操作する代わりに、ネイティブに商品を検索し、カートを管理して、食料品の注文を準備できます。

🟢 v0.3 — 動作確認済みで、DataDome にも対応しています。 8 つすべてのツールが、実際のサイトに対するエンドツーエンドの検証を通過しています。リクエストは CDP 経由で操作する実際の Chrome 内で実行されるため、ヘッドレスクライアントや Cookie の再利用をブロックする DataDome のボット対策を通過できます。最初に開くウィンドウで Leclerc Drive にログインすると、そのセッションは保持されます。リバースエンジニアリングした API については、docs/api-capture.md をご覧ください。

理由

E.Leclerc Drive には公開 API がありません。現在、自動化する唯一の方法はブラウザーの自動操作ですが、時間がかかり（商品ごとに約 3〜5 秒）、不安定です（状況を考慮しないクリック）。このプロジェクトでは、内部の操作を適切な MCP ツールとして公開するため、任意の MCP クライアント（Claude Desktop、Claude Code）から直接操作できます。

ツール

ツール	説明
find_stores(query)	郵便番号または都市名の近くにあるドライブを検索します → 名前、ID、サービス種別、距離、ホスト。
set_store(store_id)	利用する店舗を選択して記憶します（適切なホストを自動的に解決します）。
get_store()	現在選択されている店舗を表示します。
search_product(query)	カタログを検索します → 価格、1 kg あたりの価格、Nutri-Score、在庫状況、id を含む商品。
add_to_cart(product_id, quantity?)	商品をカートに追加します。
remove_from_cart(product_id)	カートから商品を削除します。
update_quantity(product_id, quantity)	商品の数量を設定します（0 にすると削除されます）。
get_cart()	合計金額を含むカートの全内容を取得します。

ステータス

• Leclerc Drive のエンドポイントをリバースエンジニアリングしました（検索／カート／店舗検索 — docs/api-capture.md を参照）
• 8 つすべてのツールが、実際の店舗に対するエンドツーエンドの検証を通過しました
• 実行時の店舗選択と永続化（find_stores / set_store）
• v0.3：実際の Chrome を CDP 経由で操作し、DataDome に対応（Cookie の再利用を阻止したアクティブなボットチャレンジを突破）✅
• npm および MCP レジストリに公開済み
• チェックアウト／配送時間枠の予約

要件

• Node.js ≥ 22（組み込みの WebSocket を使用）
• Google Chrome のインストールが必要です（サーバーは CDP 経由で Chrome を操作します）

開発用インストール

git clone https://github.com/skunkobi/mcp-leclerc-drive.git
cd mcp-leclerc-drive
npm install
npm run build

認証の仕組み（CDP 経由の実際の Chrome）

Leclerc Drive は DataDome によって保護されており、アクティブチャレンジモードに移行すると、ブラウザー以外のトラフィック（ヘッドレスクライアント、Cookie の再利用）は HTTP 403 でブロックされます。確実に通過できるのは、チャレンジを実行する実際のブラウザーだけです。そのため、このサーバーでは次のようにしています。

1. 最初のリクエスト時に、専用の永続プロファイル（~/.mcp-leclerc-drive/chrome）とデバッグポートを指定して、インストール済みの Google Chrome を起動します。自動化フラグは使用しないため、navigator.webdriver は false のままです。
2. Chrome のウィンドウが開きます。そのウィンドウで Leclerc Drive に一度ログインしてください。永続プロファイルにより、再起動後もログイン状態が維持されます。
3. すべてのリクエストは CDP 経由でそのページ内から実行されるため、ブラウザーの Cookie、TLS フィンガープリント、解決済みの DataDome チャレンジが使われ、リクエストが通過します。

Cookie は読み取られず、保存もされません。キーチェーンの確認画面も表示されません。サーバーは Chrome と同じマシンで実行する必要があり、ウィンドウも開きます（DataDome はヘッドレスを検出できるため、リスクを理解していない場合は有効にしないでください）。

Env var	Default	Description
LECLERC_STORE_ID	053701	デフォルトの店舗 ID（実行時に set_store で上書きされます）。
LECLERC_HOST	fd9-courses.leclercdrive.fr	デフォルトのバックエンドホスト（fdN のプレフィックスは店舗によって異なります）。
LECLERC_CHROME_PATH	auto	Chrome がデフォルトの場所にない場合に指定する、Chrome バイナリのパスです。
LECLERC_CHROME_PROFILE_DIR	~/.mcp-leclerc-drive/chrome	Chrome の永続プロファイルディレクトリです。
LECLERC_CHROME_PORT	9222	CDP のリモートデバッグポートです。
LECLERC_HEADLESS	false	Chrome をヘッドレスで実行します（⚠️ DataDome に検出されます。推奨しません）。
LECLERC_MIN_INTERVAL_MS	1000	2 件のリクエスト間に設ける最小遅延（適切な利用のため）。
LECLERC_JITTER_MS	400	リクエスト間に追加するランダムなジッターです。
LECLERC_MAX_RETRIES	3	あきらめる前に、一時的な 403/429 に対して再試行する回数です。
LECLERC_BACKOFF_BASE_MS	1500	再試行時の基本バックオフ時間（試行ごとに倍増します）。

DataDome の処理をブラウザーが担うようになっても、適切な利用のため、サーバーは引き続きリクエストを直列化して間隔を空けます（単一キュー、約 1 秒＋ジッター、バックオフ付き再試行）。

店舗の選択（環境変数は不要）

最も簡単な方法は、会話の中で尋ねることです。環境変数は必要ありません。

> "trouve mon drive vers 44000"     → find_stores lists nearby drives
> "prends Rezé Atout Sud"           → set_store remembers it (correct host resolved)
> "cherche du lait"                  → runs on that store

set_store は選択内容を ~/.mcp-leclerc-drive/config.json に保存するため、セッションをまたいで維持されます。また、適切なバックエンドホストを自動で解決します（fdN のプレフィックスは店舗によって実際に異なり、fd8、fd9、fd14 などがあります）。

⚠️ 一度に利用できるのは 1 つのドライブだけです。 Leclerc はセッションを単一のドライブに紐付けます。set_store で選択する店舗は、Chrome のセッションでログインしている店舗でなければなりません。通常はご自身のドライブを使用するため、これが一般的なケースです。ブラウザーで利用していない任意の別のドライブに切り替えると、「セッションの有効期限が切れました」というエラーが返されます。

必要であれば、環境変数 LECLERC_STORE_ID／LECLERC_HOST で店舗を明示的に設定することもできます（例：ヘッドレスでデプロイする場合）。手動で確認するには、Drive の URL を見てください。URL は https://fd9-courses.leclercdrive.fr/magasin-053701-053701-Your-Town/ のような形式です。6 桁の数字が店舗 ID で、fdN-courses.leclercdrive.fr の部分がホストです。

Claude Desktop / Claude Code（mcp 設定）

npm から直接インストールできます。クローンは不要です。

# Claude Code
claude mcp add leclerc-drive -- npx -y mcp-leclerc-drive

または、Claude Desktop の設定で次のようにします。

{
  "mcpServers": {
    "leclerc-drive": {
      "command": "npx",
      "args": ["-y", "mcp-leclerc-drive"]
    }
  }
}

環境変数は不要です。会話の中で find_stores／set_store を使って店舗を選択してください。初回利用時に Chrome のウィンドウが開きます。Leclerc Drive に一度ログインすれば、準備完了です。

開発

npm run dev        # tsc --watch
npm run typecheck  # type-check without emitting
npm run inspect    # run under the MCP Inspector

アーキテクチャ

src/
  index.ts          # MCP server: registers the 8 tools over stdio
  config.ts         # env-based config (store, host, Chrome/CDP, throttle)
  types.ts          # Product / CartItem / Cart
  store.ts          # active store selection + persistence (~/.mcp-leclerc-drive)
  browser.ts        # ChromeSession: drives real Chrome via CDP → beats DataDome
  leclerc/
    client.ts       # Leclerc Drive backend client (search + cart)
    locator.ts      # store finder: postal code / city → nearby drives
    throttle.ts     # request serialization + spacing + retry (hygiene)
docs/
  api-capture.md    # the reverse-engineered Leclerc Drive API

貢献

このツールはコミュニティによって開発されています。バグ修正、お使いの店舗への対応、新機能（チェックアウト、配送時間枠、保存済みリストなど）の追加を問わず、貢献を心より歓迎します。

開発環境のセットアップ、ご自身のアカウントを使ったスモークテスト（npm run smoke）、そしてこのプロジェクトで特に役立つ、新しい Leclerc Drive エンドポイントをリバースエンジニアリングして組み込む方法を簡潔にまとめたガイドについては、**CONTRIBUTING.md**をご覧ください。取り組みやすい最初の課題は、上記のステータスチェックリストに記載されています。

フィードバックとお問い合わせ

フィードバック、バグ報告、アイデアを心より歓迎します。

• Issue／PR： リポジトリでIssue を作成してください。
• メール： [email protected]

免責事項

非公式プロジェクトです。E.Leclerc との提携関係はなく、同社から承認も受けていません。ご自身のアカウントを使用し、ご自身の責任において、サイトの利用規約に従ってご利用ください。ご自身の食料品購入を個人的に自動化することを目的としています。

ライセンス

MIT