Italy Logistics (buy Poste Italiane + more labels + tracking via Shippo)

Official3 toolsLive

by junter1989k-ai · JavaScript

Italy shipping labels for AI agents: buy Poste Italiane and more, track and refund via Shippo.

Topics

ai-agentclaudeitalylogisticsmcpmcp-serverposte-italianeshippingshippowishpool

Captured live from the server via tools/list.

create_shipment

Create a Italy 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: Poste Italiane domestic parcels via the Shippo master account — no Poste Italiane contract or merchant account needed (Italy domestic only) — so an agent can print a Poste Italiane 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 provincia (provincia is optional for Italy addresses).
to_zip	string	required	Recipient CAP (e.g. "20121"). Required.
to_country	string	optional	Recipient ISO country code. Default IT.
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 provincia.
from_zip	string	required	Sender CAP. Required.
from_country	string	optional	Sender ISO country code. Default IT.
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. "Poste Italiane"). Default: cheapest across all available carriers.
service	string	optional	Optional: restrict to a service level name or token (e.g. "Poste Delivery Business Express"). 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 provincia (provincia is optional for Italy addresses)."
    },
    "to_zip": {
      "type": "string",
      "description": "Recipient CAP (e.g. \"20121\"). Required."
    },
    "to_country": {
      "type": "string",
      "description": "Recipient ISO country code. Default IT."
    },
    "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 provincia."
    },
    "from_zip": {
      "type": "string",
      "description": "Sender CAP. Required."
    },
    "from_country": {
      "type": "string",
      "description": "Sender ISO country code. Default IT."
    },
    "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. \"Poste Italiane\"). Default: cheapest across all available carriers."
    },
    "service": {
      "type": "string",
      "description": "Optional: restrict to a service level name or token (e.g. \"Poste Delivery Business Express\"). Default: cheapest."
    }
  },
  "required": [
    "to_name",
    "to_street1",
    "to_city",
    "to_zip",
    "from_name",
    "from_street1",
    "from_city",
    "from_zip",
    "weight"
  ]
}

query_tracking

Track a Italy 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 "poste_italiane"; 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. "poste_italiane", "usps", or "shippo" for TEST mock numbers). Default "poste_italiane".

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. \"poste_italiane\", \"usps\", or \"shippo\" for TEST mock numbers). Default \"poste_italiane\"."
    }
  },
  "required": [
    "tracking_number"
  ]
}

refund_label

Request a refund for a Italy 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

Italy Logistics MCP 🇮🇹 — How can my AI agent buy a Poste Italiane / Italian 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": {
    "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.

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/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 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 → 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.

Sister servers

UK labels (Royal Mail) live in uk-logistics-mcp; France (Mondial Relay) in france-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-it.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

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