Australia Logistics (buy Aramex + more labels + tracking via Shippo)

Official3 toolsLive

by junter1989k-ai · JavaScript

Australia shipping labels for AI agents: buy Aramex and more, track and refund via Shippo.

Topics

ai-agentaramexaustraliaclaudelogisticsmcpmcp-servershippingshippowishpool

Captured live from the server via tools/list.

create_shipment

Create a Australia 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 (AUD). Recommended carrier: Aramex Australia parcels via the Shippo master account — no Aramex contract or merchant account needed — so an agent can print a Aramex 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 state (state is optional for Australia addresses).
to_zip	string	required	Recipient postcode (e.g. "2000"). Required.
to_country	string	optional	Recipient ISO country code. Default AU.
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 state.
from_zip	string	required	Sender postcode. Required.
from_country	string	optional	Sender ISO country code. Default AU.
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. "Aramex"). Default: cheapest across all available carriers.
service	string	optional	Optional: restrict to a service level name or token (e.g. "Parcel"). 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 state (state is optional for Australia addresses)."
    },
    "to_zip": {
      "type": "string",
      "description": "Recipient postcode (e.g. \"2000\"). Required."
    },
    "to_country": {
      "type": "string",
      "description": "Recipient ISO country code. Default AU."
    },
    "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 state."
    },
    "from_zip": {
      "type": "string",
      "description": "Sender postcode. Required."
    },
    "from_country": {
      "type": "string",
      "description": "Sender ISO country code. Default AU."
    },
    "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. \"Aramex\"). Default: cheapest across all available carriers."
    },
    "service": {
      "type": "string",
      "description": "Optional: restrict to a service level name or token (e.g. \"Parcel\"). Default: cheapest."
    }
  },
  "required": [
    "to_name",
    "to_street1",
    "to_city",
    "to_zip",
    "from_name",
    "from_street1",
    "from_city",
    "from_zip",
    "weight"
  ]
}

query_tracking

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

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

refund_label

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

Australia Logistics MCP 🇦🇺 — How can my AI agent buy an Aramex / Australian 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": {
    "australia-logistics": {
      "type": "http",
      "url": "https://logi-au.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/australia-logistics-mcp && cd australia-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 Australia shipping labels — Aramex Australia parcels and more — with automatic cheapest-rate selection, track parcels, and refund unused labels via the Shippo shipping API. Aramex runs on Shippo's master account, so no Aramex 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-au.wishpool.app/mcp · Registry: app.wishpool/australia-logistics-mcp

Quick start

json

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

Aramex without an Aramex contract

Aramex Australia parcels run on Shippo's master carrier account, so an AI agent can print an Aramex label with no Aramex 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 (Aramex, Australia Post, etc.) can select it instead.

Tools

Tool	What it does
`create_shipment`	Buy an Australia label. `to_` + `from_` address fields (state optional), parcel `weight` (grams by default, required) and `length`/`width`/`height` (centimetres by default). Optional `carrier`/`service` restrict the choice (e.g. `Aramex` / `Parcel`) — 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` (AUD).
`query_tracking`	Track by `tracking_number` + `carrier` token (default `aramex`; 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 :3250 (/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; France (Mondial Relay) in france-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-au.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

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