France Logistics (buy Mondial Relay + more labels + tracking via Shippo)

Official3 toolsLive

by junter1989k-ai · JavaScript

France shipping labels for AI agents: buy Mondial Relay and more, track and refund via Shippo.

Topics

ai-agentclaudefrancelogisticsmcpmcp-servermondial-relayshippingshippowishpool

Captured live from the server via tools/list.

create_shipment

Create a France shipping label via Shippo — pass a to_address, from_address and parcel (dimensions in CENTIMETRES, weight in GRAMS by default), and the server fetches carrier rates, buys the CHEAPEST rate by default (or the carrier/service you specify), and returns the shipment_id, transaction_id, tracking_number, printable label_url and the price paid (EUR). Recommended carrier: Mondial Relay relay-point (point relais) delivery via the Shippo master account — no Mondial Relay contract or merchant account needed — so an agent can print a Mondial Relay label with no merchant courier account. Bring your own Shippo API token via header x-shippo-token: free TEST tokens (prefix shippo_test_…) run the full flow end-to-end at no cost (sign up free, no card, at apps.goshippo.com/join); production tokens (prefix shippo_live_…) buy real labels. The token prefix auto-selects the environment. weight is always required. Owner policy headers gate the label price before any purchase.

Parameters25

to_name	string	required	Recipient full name.
to_street1	string	required	Recipient street address line 1.
to_street2	string	optional	Optional recipient street address line 2 (flat/unit).
to_city	string	required	Recipient town / city.
to_state	string	optional	Optional recipient région (région is optional for France addresses).
to_zip	string	required	Recipient code postal (e.g. "75008"). Required.
to_country	string	optional	Recipient ISO country code. Default FR.
to_phone	string	optional	Optional recipient phone (some carriers/services require it).
to_email	string	optional	Optional recipient email.
from_name	string	required	Sender full name.
from_street1	string	required	Sender street address line 1.
from_street2	string	optional	Optional sender street address line 2.
from_city	string	required	Sender town / city.
from_state	string	optional	Optional sender région.
from_zip	string	required	Sender code postal. Required.
from_country	string	optional	Sender ISO country code. Default FR.
from_phone	string	optional	Optional sender phone.
weight	number	required	Parcel weight in GRAMS (g) by default. Required. Use mass_unit to change (kg/oz/lb).
mass_unit	string	optional	Weight unit: g (default), kg, oz or lb.
length	number	optional	Parcel length in CENTIMETRES (cm) by default. Provide length+width+height together.
width	number	optional	Parcel width in CENTIMETRES.
height	number	optional	Parcel height in CENTIMETRES.
distance_unit	string	optional	Dimension unit: cm (default), m, in or ft.
carrier	string	optional	Optional: restrict to a carrier (e.g. "Mondial Relay"). Default: cheapest across all available carriers.
service	string	optional	Optional: restrict to a service level name or token (e.g. "Point Relais"). Default: cheapest.

Raw schema

{
  "type": "object",
  "properties": {
    "to_name": {
      "type": "string",
      "description": "Recipient full name."
    },
    "to_street1": {
      "type": "string",
      "description": "Recipient street address line 1."
    },
    "to_street2": {
      "type": "string",
      "description": "Optional recipient street address line 2 (flat/unit)."
    },
    "to_city": {
      "type": "string",
      "description": "Recipient town / city."
    },
    "to_state": {
      "type": "string",
      "description": "Optional recipient région (région is optional for France addresses)."
    },
    "to_zip": {
      "type": "string",
      "description": "Recipient code postal (e.g. \"75008\"). Required."
    },
    "to_country": {
      "type": "string",
      "description": "Recipient ISO country code. Default FR."
    },
    "to_phone": {
      "type": "string",
      "description": "Optional recipient phone (some carriers/services require it)."
    },
    "to_email": {
      "type": "string",
      "description": "Optional recipient email."
    },
    "from_name": {
      "type": "string",
      "description": "Sender full name."
    },
    "from_street1": {
      "type": "string",
      "description": "Sender street address line 1."
    },
    "from_street2": {
      "type": "string",
      "description": "Optional sender street address line 2."
    },
    "from_city": {
      "type": "string",
      "description": "Sender town / city."
    },
    "from_state": {
      "type": "string",
      "description": "Optional sender région."
    },
    "from_zip": {
      "type": "string",
      "description": "Sender code postal. Required."
    },
    "from_country": {
      "type": "string",
      "description": "Sender ISO country code. Default FR."
    },
    "from_phone": {
      "type": "string",
      "description": "Optional sender phone."
    },
    "weight": {
      "type": "number",
      "description": "Parcel weight in GRAMS (g) by default. Required. Use mass_unit to change (kg/oz/lb)."
    },
    "mass_unit": {
      "type": "string",
      "description": "Weight unit: g (default), kg, oz or lb."
    },
    "length": {
      "type": "number",
      "description": "Parcel length in CENTIMETRES (cm) by default. Provide length+width+height together."
    },
    "width": {
      "type": "number",
      "description": "Parcel width in CENTIMETRES."
    },
    "height": {
      "type": "number",
      "description": "Parcel height in CENTIMETRES."
    },
    "distance_unit": {
      "type": "string",
      "description": "Dimension unit: cm (default), m, in or ft."
    },
    "carrier": {
      "type": "string",
      "description": "Optional: restrict to a carrier (e.g. \"Mondial Relay\"). Default: cheapest across all available carriers."
    },
    "service": {
      "type": "string",
      "description": "Optional: restrict to a service level name or token (e.g. \"Point Relais\"). Default: cheapest."
    }
  },
  "required": [
    "to_name",
    "to_street1",
    "to_city",
    "to_zip",
    "from_name",
    "from_street1",
    "from_city",
    "from_zip",
    "weight"
  ]
}

query_tracking

Track a France shipment by its tracking_number (the one create_shipment returned, or any carrier tracking number) plus its carrier. Returns the current status with a plain-English hint. Status values (Shippo enum): UNKNOWN, PRE_TRANSIT (label made, not yet picked up), TRANSIT, DELIVERED, RETURNED, FAILURE. Raw carrier scan details are always included. carrier defaults to "mondial_relay"; for TEST tokens use carrier="shippo" with mock numbers SHIPPO_TRANSIT / SHIPPO_DELIVERED. Safe to call anytime.

Parameters2

tracking_number	string	required	The tracking number to look up (from create_shipment or a carrier).
carrier	string	optional	Carrier token for the lookup (e.g. "mondial_relay", "usps", or "shippo" for TEST mock numbers). Default "mondial_relay".

Raw schema

{
  "type": "object",
  "properties": {
    "tracking_number": {
      "type": "string",
      "description": "The tracking number to look up (from create_shipment or a carrier)."
    },
    "carrier": {
      "type": "string",
      "description": "Carrier token for the lookup (e.g. \"mondial_relay\", \"usps\", or \"shippo\" for TEST mock numbers). Default \"mondial_relay\"."
    }
  },
  "required": [
    "tracking_number"
  ]
}

refund_label

Request a refund for a France shipping label bought via create_shipment, by its transaction_id. Refund is only possible for UNUSED labels that were never scanned by the carrier; already-shipped labels cannot be refunded. Returns refund_status: QUEUED / PENDING (accepted, carrier still processing — most common), SUCCESS (money returned), or ERROR (not eligible, e.g. already scanned). Carriers can take time to move QUEUED/PENDING → SUCCESS.

Parameters1

transaction_id

string

required

The transaction_id returned by create_shipment (the bought label to refund).

Raw schema

{
  "type": "object",
  "properties": {
    "transaction_id": {
      "type": "string",
      "description": "The transaction_id returned by create_shipment (the bought label to refund)."
    }
  },
  "required": [
    "transaction_id"
  ]
}

README.md6 KBView on GitHub

France Logistics MCP 🇫🇷 — How can my AI agent buy a Mondial Relay / French shipping label?

Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

json

{
  "mcpServers": {
    "france-logistics": {
      "type": "http",
      "url": "https://logi-fr.wishpool.app/mcp"
    }
  }
}

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.

Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

bash

git clone https://github.com/junter1989k-ai/france-logistics-mcp && cd france-logistics-mcp && npx vercel --prod

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

Remote MCP server that lets any AI agent buy France shipping labels (étiquettes d'expédition) — Mondial Relay relay-point delivery and more — with automatic cheapest-rate selection, track parcels, and refund unused labels via the Shippo shipping API. Mondial Relay runs on Shippo's master account, so no Mondial Relay contract or merchant courier account is needed. Stateless, bring-your-own API token, never stores anything. Free Shippo test tokens give zero-cost end-to-end labels.

Live endpoint: https://logi-fr.wishpool.app/mcp · Registry: app.wishpool/france-logistics-mcp

Quick start

json

{
  "mcpServers": {
    "france-logistics": {
      "type": "http",
      "url": "https://logi-fr.wishpool.app/mcp",
      "headers": {
        "x-shippo-token": "shippo_test_your_test_or_shippo_live_prod_token"
      }
    }
  }
}

No shared demo — but test tokens are free. Shippo issues free TEST tokens (prefix shippo_test_…) that run the full flow end-to-end at no cost: sign up with no card at apps.goshippo.com/join → API. Production tokens (prefix shippo_live_…) buy real labels. The same server auto-selects the environment from the token prefix.

Mondial Relay without a Mondial Relay contract

Mondial Relay runs on Shippo's master carrier account, so an AI agent can print a Mondial Relay label with no Mondial Relay contract and no merchant courier account — just a free Shippo token. Mondial Relay is a relay-point (point relais) delivery network — parcels are dropped at and collected from relay points. The carrier parameter stays open, so a merchant with its own carrier account on Shippo (Mondial Relay, Colissimo, etc.) can select it instead.

Tools

Tool	What it does
`create_shipment`	Buy a France label. `to_` + `from_` address fields (région/state optional), parcel `weight` (grams by default, required) and `length`/`width`/`height` (centimetres by default). Optional `carrier`/`service` restrict the choice (e.g. `Mondial Relay` / `Point Relais`) — default is the cheapest rate across all available carriers. Mondial Relay is relay-point delivery. Fetches rates, buys the chosen rate, returns `shipment_id`, `transaction_id`, `tracking_number`, printable `label_url`, `carrier`, `service` and the `rate` (EUR).
`query_tracking`	Track by `tracking_number` + `carrier` token (default `mondial_relay`; use `shippo` with `SHIPPO_TRANSIT`/`SHIPPO_DELIVERED` for TEST tokens). Returns `status` from the Shippo enum — `UNKNOWN` / `PRE_TRANSIT` / `TRANSIT` / `DELIVERED` / `RETURNED` / `FAILURE` — plus a plain-English hint; non-terminal statuses carry `next_steps`. Raw carrier scans always included.
`refund_label`	Refund an unused label by `transaction_id`. Returns `refund_status`: `QUEUED` / `PENDING` / `SUCCESS` / `ERROR`. Only labels never scanned by the carrier are eligible — an already-shipped label cannot be refunded.

Owner policy guardrails ride optional headers (x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools) — set by the human owner in client config; the agent cannot relax them. The label price is gated before any purchase: approval-above returns an unsigned draft with the shipment/rates prepared but no label bought.

Develop

bash

node test/serve.js   # local server on :3249 (/mcp)
node test/e2e.js     # protocol + validation + policy/shippo units + fake-token live probe to api.goshippo.com (expects native 401)

How it talks to Shippo

create_shipment is two server-to-server REST calls: POST /shipments/ (to/from address + parcel → rates[]) then POST /transactions/ (chosen rate object_id → label_url + tracking_number). query_tracking is GET /tracks/{carrier}/{tracking_number}. refund_label is POST /refunds/ (by transaction id). Auth is the header Authorization: ShippoToken <token>; the token prefix (shippo_test_… / shippo_live_…) selects test vs production on the same base URL https://api.goshippo.com.

Safety

Pure stateless translation layer. The label is generated and served by Shippo/the carrier; the Shippo API token travels per-request in a header, nothing is stored. Parcels flow sender ↔ carrier ↔ recipient directly. Privacy policy.

Sister servers

UK labels (Royal Mail) live in uk-logistics-mcp; Germany (Deutsche Post) in germany-logistics-mcp; Australia (Aramex) in australia-logistics-mcp; US labels (USPS/UPS/FedEx) in usa-logistics-mcp; Taiwan CVS pickup + home delivery in taiwan-logistics-mcp. One family of stateless BYO local-commerce MCP servers: local payments in 81 countries at mcp.wishpool.app, plus electronic-invoice servers across nine countries including Mexico CFDI, Brazil NF-e, Chile DTE, Peru CPE and India GST.

MIT licensed.

Install

Tools (3)

create_shipmentquery_trackingrefund_label

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://logi-fr.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "france-logistics-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://logi-fr.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.