# Italy Logistics MCP 🇮🇹 — How can my AI agent buy a Poste Italiane / Italian shipping label?

<!-- install-cta -->
## Use it in 60 seconds

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

```json
{
  "mcpServers": {
    "italy-logistics": {
      "type": "http",
      "url": "https://logi-it.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](https://mcp.wishpool.app/trust).

### 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:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/junter1989k-ai/italy-logistics-mcp)

```bash
git clone https://github.com/junter1989k-ai/italy-logistics-mcp && cd italy-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 **Italian shipping labels** (etichette di spedizione) — Poste Italiane parcels and more — with automatic **cheapest-rate selection**, track parcels, and refund unused labels via the [Shippo](https://www.goshippo.com/) shipping API. **Poste Italiane runs on Shippo's master account, so no Poste Italiane 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-it.wishpool.app/mcp` · Registry: `app.wishpool/italy-logistics-mcp`

## Quick start

```json
{
  "mcpServers": {
    "italy-logistics": {
      "type": "http",
      "url": "https://logi-it.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](https://apps.goshippo.com/join) → API. Production tokens (prefix `shippo_live_…`) buy real labels. The same server auto-selects the environment from the token prefix.

## Poste Italiane without a Poste Italiane contract

Poste Italiane parcels run on **Shippo's master carrier account**, so an AI agent can print a Poste Italiane label with **no Poste Italiane contract and no merchant courier account** — just a free Shippo token. The `carrier` parameter stays open, so a merchant with its own carrier account on Shippo (Poste Italiane, DHL, etc.) can select it instead.

## Tools

| Tool | What it does |
|---|---|
| `create_shipment` | Buy an Italian label. `to_*` + `from_*` address fields (provincia/state optional), parcel `weight` (grams by default, required) and `length`/`width`/`height` (centimetres by default). Optional `carrier`/`service` restrict the choice (e.g. `Poste Italiane` / `Delivery Business Express`) — default is the **cheapest** rate across all available carriers. 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 `poste_italiane`; 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 :3248 (/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](https://logi-it.wishpool.app/privacy).

## Sister servers

UK labels (Royal Mail) live in [uk-logistics-mcp](https://logi-uk.wishpool.app); France (Mondial Relay) in [france-logistics-mcp](https://logi-fr.wishpool.app); Australia (Aramex) in [australia-logistics-mcp](https://logi-au.wishpool.app); US labels (USPS/UPS/FedEx) in [usa-logistics-mcp](https://logi-us.wishpool.app); Taiwan CVS pickup + home delivery in [taiwan-logistics-mcp](https://logi-tw.wishpool.app). One family of stateless BYO local-commerce MCP servers: local payments in 81 countries at [mcp.wishpool.app](https://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.