UK Logistics (buy Royal Mail + more labels + tracking via Shippo)

Official3 toolsLive

by junter1989k-ai · JavaScript

UK shipping labels for AI agents: buy Royal Mail Tracked and more, track and refund via Shippo.

Topics

ai-agentclaudelogisticsmcpmcp-serverroyal-mailshippingshippoukwishpool

Captured live from the server via tools/list.

create_shipment

Create a United Kingdom 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 (GBP). Recommended carrier: Royal Mail Tracked 24/48 via the Shippo master account — no Royal Mail contract or merchant account needed — so an agent can print a Royal Mail 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 county (county is optional for United Kingdom addresses).
to_zip	string	required	Recipient postcode (e.g. "SW1A 1AA"). Required.
to_country	string	optional	Recipient ISO country code. Default GB.
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 county.
from_zip	string	required	Sender postcode. Required.
from_country	string	optional	Sender ISO country code. Default GB.
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. "Royal Mail"). Default: cheapest across all available carriers.
service	string	optional	Optional: restrict to a service level name or token (e.g. "Tracked 24/48"). 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 county (county is optional for United Kingdom addresses)."
    },
    "to_zip": {
      "type": "string",
      "description": "Recipient postcode (e.g. \"SW1A 1AA\"). Required."
    },
    "to_country": {
      "type": "string",
      "description": "Recipient ISO country code. Default GB."
    },
    "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 county."
    },
    "from_zip": {
      "type": "string",
      "description": "Sender postcode. Required."
    },
    "from_country": {
      "type": "string",
      "description": "Sender ISO country code. Default GB."
    },
    "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. \"Royal Mail\"). Default: cheapest across all available carriers."
    },
    "service": {
      "type": "string",
      "description": "Optional: restrict to a service level name or token (e.g. \"Tracked 24/48\"). Default: cheapest."
    }
  },
  "required": [
    "to_name",
    "to_street1",
    "to_city",
    "to_zip",
    "from_name",
    "from_street1",
    "from_city",
    "from_zip",
    "weight"
  ]
}

query_tracking

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

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

refund_label

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

UK Logistics MCP 🇬🇧 — How can my AI agent buy a Royal Mail / UK 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": {
    "uk-logistics": {
      "type": "http",
      "url": "https://logi-uk.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/uk-logistics-mcp && cd uk-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 UK shipping labels — Royal Mail Tracked 24/48 and more — with automatic cheapest-rate selection, track parcels, and refund unused labels via the Shippo shipping API. Royal Mail runs on Shippo's master account, so no Royal Mail 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-uk.wishpool.app/mcp · Registry: app.wishpool/uk-logistics-mcp

Quick start

json

{
  "mcpServers": {
    "uk-logistics": {
      "type": "http",
      "url": "https://logi-uk.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.

Royal Mail without a Royal Mail contract

Royal Mail Tracked 24/48 runs on Shippo's master carrier account, so an AI agent can print a Royal Mail label with no Royal Mail 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 can select it instead.

Tools

Tool	What it does
`create_shipment`	Buy a UK label. `to_` + `from_` address fields (county/state optional), parcel `weight` (grams by default, required) and `length`/`width`/`height` (centimetres by default). Optional `carrier`/`service` restrict the choice (e.g. `Royal Mail` / `Tracked 24`) — 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` (GBP).
`query_tracking`	Track by `tracking_number` + `carrier` token (default `royal_mail`; 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 :3247 (/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

US labels (USPS/UPS/FedEx) live 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-uk.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

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