French Grocery

fr-grocery-mcp

An MCP server that gives an agent domain-level access to the online grocery services ("drive") of French retailers: E.Leclerc Drive and Super U (coursesu.com) today, others through a new adapter. Search products, read their composition, manage the cart, read slots and minimum order amounts, compare carts. Nothing else.

The reasoning (recipes, ingredients, quantities for N people, product choice, price/promotion trade-offs) belongs to the agent. For example:

Order what I need to cook spaghetti bolognese and a four-cheese pizza for 4, at the cheapest of Leclerc and Super U.

The agent builds the list, searches each ingredient at each retailer, fills the carts, then compares them. The order is never placed: slot booking and payment are left to the user, on the site.

[!WARNING] This project is not affiliated with, endorsed by or supported by E.Leclerc, Système U or any retailer. It drives your own logged-in browser session, at a human pace, for personal use. Retailer sites change without notice and their terms of use apply: use it at your own risk.

Tools

Every retailer tool takes store (leclerc, superu: an enum generated from the configuration).

Every change reads the cart back and returns confirmed: true if the site holds the targeted quantity. Results are typed (outputSchema + structuredContent) and the server sends instructions describing the flow to the agent. A cap of 50 units per product guards against unit mistakes.

Errors (isError, error field): ValidationError (fix the call), NotSupportedError (the retailer does not support it), SessionExpiredError (log in again in Chrome), SiteBlockedError (anti-bot: stop), TransientError (retried automatically, then reported).

Product labels, promotion texts and search terms stay in French, as on the sites.

Capabilities per retailer

Requirements

• Node ≥ 26 (runs TypeScript natively: no build step). With mise: mise install --locked installs the version recorded in mise.lock.
• A Chrome started with --remote-debugging-port=9222 and logged in to the sites (mise run chrome starts a dedicated profile in ~/.fr-grocery-mcp/chrome). One tab per site is found, or opened, by its domain.

Requests go through the browser session, one at a time and spaced out: the server replays what the site does on a click (see docs/retailers/). No protection is bypassed: an anti-bot block stops the server, it is never retried.

Configuration

FR_GROCERY_CONFIG points to a JSON file. Without a file, only Super U is plugged in.

{
  "chrome": { "port": 9222, "timeoutMs": 30000 },
  "stores": [
    {
      "retailer": "leclerc",
      "store": {
        "storeId": "123456",
        "retrievalPointId": "123456",
        "host": "fd7-courses.leclercdrive.fr",
        "name": "My Leclerc Drive"
      }
    },
    { "retailer": "superu", "minIntervalMs": 300 }
  ]
}

The order of the retailers is the order of preference. minIntervalMs sets the spacing between requests (default: 1000 ms for Leclerc, 300 ms for Super U). Your Leclerc store's values can be found with find_stores / set_store: the store picked with set_store is remembered in $FR_GROCERY_STATE_DIR/leclerc-store.json (default ~/.fr-grocery-mcp) and takes precedence over the configuration. FR_GROCERY_CHROME_PORT overrides the port of the file. The Super U store is chosen on coursesu.com.

Usage

The server is distributed as the fr-grocery-mcp npm package and runs locally over stdio. Claude Code (.mcp.json):

{
  "mcpServers": {
    "fr-grocery-mcp": {
      "command": "npx",
      "args": ["-y", "fr-grocery-mcp@latest"],
      "env": { "FR_GROCERY_CONFIG": "/path/to/fr-grocery-mcp.json" }
    }
  }
}

Pin an exact version (for example fr-grocery-mcp@0.2.0) instead of @latest for a reproducible setup. The same package is described in the official MCP Registry by io.github.maxime-desmarchelier/fr-grocery-mcp. Each release is published on npm, GitHub Releases and the MCP Registry; see docs/releasing.md.

From a source checkout, use "command": "node" and "args": ["/path/to/fr-grocery-mcp/src/main.ts"] instead. Manual inspection: npm run inspect (MCP Inspector).

Development

npm ci
npm run check                      # typecheck + lint + tests with coverage thresholds
mise run lint                      # the git hook's ruleset on the whole repository (what CI runs)
npm test                           # unit, adapter contract, integration (no access to the sites)
npm run doctor                     # real sites, read-only: session, search, product page, cart per retailer
npm run test:live                  # real sites: changes then removes an item that is not in the cart
LIVE_STORES=leclerc npm run test:live
npm run fixtures -- leclerc        # captures a retailer's reference pages again
npm run format                     # Biome

Architecture and technical choices: docs/architecture.md. Adding a retailer: docs/adding-a-retailer.md. Releases: docs/releasing.md.

Contributing

Issues and pull requests are welcome: see CONTRIBUTING.md for the setup, the code rules and what npm run check must show before a pull request. main is protected and CI must be green.

Security

Please report vulnerabilities privately through the repository's Security tab, never in a public issue: see SECURITY.md.

License

MIT. The E.Leclerc Drive adapter builds on knowledge from mcp-leclerc-drive (MIT): see NOTICE.