USA Logistics (buy USPS/UPS/FedEx labels + tracking via EasyPost)

Official3 toolsLive

by junter1989k-ai · JavaScript

US shipping labels for AI agents: buy USPS/UPS/FedEx, track and refund via EasyPost.

Topics

ai-agentclaudeeasypostlogisticsmcpmcp-servershippingusawishpool

Captured live from the server via tools/list.

create_shipment

Create a US shipping label via EasyPost — pass a to_address, from_address and parcel (dimensions in INCHES, weight in OUNCES); the server fetches carrier rates (USPS / UPS / FedEx etc.), buys the CHEAPEST rate by default (or the carrier/service you specify), and returns the shipment_id, tracking_code, printable label_url and the price paid. Bring your own EasyPost API key via header x-easypost-api-key: free TEST keys (prefix EZTK…) buy real USPS test labels end-to-end at no cost (sign up at easypost.com → API Keys); production keys (prefix EZAK…) buy real postage. The key prefix auto-selects the environment. weight (oz) is always required. Owner policy headers gate the label price before any purchase.

Parameters23

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 (apt/suite).
to_city	string	required	Recipient city.
to_state	string	required	Recipient state — 2-letter code for US (e.g. CA, NY).
to_zip	string	required	Recipient ZIP / postal code.
to_country	string	optional	Recipient ISO country code. Default US.
to_phone	string	optional	Optional recipient phone (some carriers/services require it).
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 city.
from_state	string	required	Sender state — 2-letter code for US.
from_zip	string	required	Sender ZIP / postal code.
from_country	string	optional	Sender ISO country code. Default US.
from_phone	string	optional	Optional sender phone.
weight	number	required	Parcel weight in OUNCES (oz). Required. 1 lb = 16 oz.
length	number	optional	Parcel length in INCHES. Provide length+width+height together, or use predefined_package instead.
width	number	optional	Parcel width in INCHES.
height	number	optional	Parcel height in INCHES.
predefined_package	string	optional	Optional carrier predefined package instead of dimensions (e.g. USPS "FlatRateEnvelope", "Parcel"). If set, length/width/height may be omitted.
carrier	string	optional	Optional: restrict to a carrier (e.g. USPS, UPS, FedEx). Default: cheapest across all available carriers.
service	string	optional	Optional: restrict to a service level (e.g. Priority, First, Ground). 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 (apt/suite)."
    },
    "to_city": {
      "type": "string",
      "description": "Recipient city."
    },
    "to_state": {
      "type": "string",
      "description": "Recipient state — 2-letter code for US (e.g. CA, NY)."
    },
    "to_zip": {
      "type": "string",
      "description": "Recipient ZIP / postal code."
    },
    "to_country": {
      "type": "string",
      "description": "Recipient ISO country code. Default US."
    },
    "to_phone": {
      "type": "string",
      "description": "Optional recipient phone (some carriers/services require it)."
    },
    "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 city."
    },
    "from_state": {
      "type": "string",
      "description": "Sender state — 2-letter code for US."
    },
    "from_zip": {
      "type": "string",
      "description": "Sender ZIP / postal code."
    },
    "from_country": {
      "type": "string",
      "description": "Sender ISO country code. Default US."
    },
    "from_phone": {
      "type": "string",
      "description": "Optional sender phone."
    },
    "weight": {
      "type": "number",
      "description": "Parcel weight in OUNCES (oz). Required. 1 lb = 16 oz."
    },
    "length": {
      "type": "number",
      "description": "Parcel length in INCHES. Provide length+width+height together, or use predefined_package instead."
    },
    "width": {
      "type": "number",
      "description": "Parcel width in INCHES."
    },
    "height": {
      "type": "number",
      "description": "Parcel height in INCHES."
    },
    "predefined_package": {
      "type": "string",
      "description": "Optional carrier predefined package instead of dimensions (e.g. USPS \"FlatRateEnvelope\", \"Parcel\"). If set, length/width/height may be omitted."
    },
    "carrier": {
      "type": "string",
      "description": "Optional: restrict to a carrier (e.g. USPS, UPS, FedEx). Default: cheapest across all available carriers."
    },
    "service": {
      "type": "string",
      "description": "Optional: restrict to a service level (e.g. Priority, First, Ground). Default: cheapest."
    }
  },
  "required": [
    "to_name",
    "to_street1",
    "to_city",
    "to_state",
    "to_zip",
    "from_name",
    "from_street1",
    "from_city",
    "from_state",
    "from_zip",
    "weight"
  ]
}

query_tracking

Track a US shipment by its tracking_code (the one create_shipment returned, or any USPS/UPS/FedEx tracking number). Returns the current status plus a plain-English hint. Status values (EasyPost enum): unknown, pre_transit (label made, not yet picked up), in_transit, out_for_delivery, delivered, available_for_pickup, return_to_sender, failure, cancelled, error. Raw carrier scan details are always included. Passing the carrier speeds detection. Safe to call anytime.

Parameters2

tracking_code	string	required	The tracking number to look up (from create_shipment or a carrier).
carrier	string	optional	Optional carrier hint (e.g. USPS, UPS, FedEx) — helps EasyPost resolve the code faster.

Raw schema

{
  "type": "object",
  "properties": {
    "tracking_code": {
      "type": "string",
      "description": "The tracking number to look up (from create_shipment or a carrier)."
    },
    "carrier": {
      "type": "string",
      "description": "Optional carrier hint (e.g. USPS, UPS, FedEx) — helps EasyPost resolve the code faster."
    }
  },
  "required": [
    "tracking_code"
  ]
}

refund_label

Request a refund for a US shipping label bought via create_shipment, by shipment_id (preferred) or by tracking_code. Refund is only possible for UNUSED labels — e.g. USPS labels can be refunded within 30 days of creation ONLY IF the parcel was never scanned by USPS; already-shipped labels cannot be refunded. Returns refund_status: submitted (accepted, carrier still processing — most common), refunded (money returned), rejected (not eligible, e.g. already scanned), or not_applicable. Carriers can take up to ~30 days to move submitted → refunded.

Parameters3

shipment_id	string	optional	The shipment_id returned by create_shipment (preferred — refunds that exact label).
tracking_code	string	optional	Alternative to shipment_id: the tracking_code to refund. Requires carrier (defaults to USPS).
carrier	string	optional	Carrier for the tracking_code path (default USPS). Ignored when shipment_id is used.

Raw schema

{
  "type": "object",
  "properties": {
    "shipment_id": {
      "type": "string",
      "description": "The shipment_id returned by create_shipment (preferred — refunds that exact label)."
    },
    "tracking_code": {
      "type": "string",
      "description": "Alternative to shipment_id: the tracking_code to refund. Requires carrier (defaults to USPS)."
    },
    "carrier": {
      "type": "string",
      "description": "Carrier for the tracking_code path (default USPS). Ignored when shipment_id is used."
    }
  }
}

README.md5 KBView on GitHub

USA Logistics MCP 🇺🇸 — How can my AI agent buy a USPS / UPS / FedEx 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": {
    "usa-logistics": {
      "type": "http",
      "url": "https://logi-us.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/usa-logistics-mcp && cd usa-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 US shipping labels — USPS, UPS, FedEx and more — with automatic cheapest-rate selection, track parcels, and refund unused labels via the EasyPost shipping API. Stateless, bring-your-own API key, never stores anything. Free EasyPost test keys give zero-cost end-to-end labels.

Live endpoint: https://logi-us.wishpool.app/mcp · Registry: app.wishpool/usa-logistics-mcp

Quick start

json

{
  "mcpServers": {
    "usa-logistics": {
      "type": "http",
      "url": "https://logi-us.wishpool.app/mcp",
      "headers": {
        "x-easypost-api-key": "EZTK_your_test_or_EZAK_prod_key"
      }
    }
  }
}

No shared demo — but test keys are free. EasyPost issues free TEST keys (prefix EZTK…) that buy real USPS test labels end-to-end at no cost: sign up at easypost.com → API Keys. Production keys (prefix EZAK…) buy real postage. The same server auto-selects the environment from the key prefix.

Tools

Tool	What it does
`create_shipment`	Buy a US label. `to_` + `from_` address fields, parcel `weight` (ounces, required) and either `length`/`width`/`height` (inches) or `predefined_package`. Optional `carrier`/`service` restrict the choice — default is the cheapest rate across all enabled carriers. Fetches rates, buys the chosen rate, returns `shipment_id`, `tracking_code`, printable `label_url`, `carrier`, `service` and the `rate` (USD).
`query_tracking`	Track by `tracking_code` (+ optional `carrier` hint). Returns `status` from the EasyPost enum — `unknown` / `pre_transit` / `in_transit` / `out_for_delivery` / `delivered` / `available_for_pickup` / `return_to_sender` / `failure` / `cancelled` / `error` — plus a plain-English hint; non-terminal statuses carry `next_steps`. Raw carrier scans always included.
`refund_label`	Refund an unused label by `shipment_id` (preferred) or `tracking_code` (+`carrier`, default USPS). Returns `refund_status`: `submitted` / `refunded` / `rejected` / `not_applicable`. USPS: within 30 days of creation and only if never scanned — 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 :3236 (/mcp)
node test/e2e.js     # protocol + validation + policy/easypost units + fake-key live probe to api.easypost.com (expects native 401)

How it talks to EasyPost

create_shipment is two server-to-server REST calls: POST /v2/shipments (to/from address + parcel → rates[]) then POST /v2/shipments/{id}/buy (chosen rate → postage_label.label_url + tracking_code). query_tracking is POST /v2/trackers (by tracking_code). refund_label is POST /v2/shipments/{id}/refund (or POST /v2/refunds by carrier + tracking_codes). Auth is HTTP Basic with the API key as username and an empty password; the key prefix (EZTK… / EZAK…) selects test vs production on the same base URL https://api.easypost.com.

Safety

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

Sister servers

Taiwan CVS pickup + home delivery live 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-us.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

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