MCP server: Shippo's hosted MCP at https://mcp.shippo.com, with per-user Shippo OAuth. You authorize once through Shippo on first use, with nothing to copy or configure, and the client refreshes the token automatically.
Point your MCP client at the hosted server:
{
"mcpServers": {
"shippo": {
"type": "http",
"url": "https://mcp.shippo.com"
}
}
}
On first use, your client runs the Shippo OAuth sign-in (in OpenClaw, openclaw mcp login shippo; in Claude Code, /mcp). No local Node process and nothing to store.
Prerequisites: A Shippo account and at least one carrier account (Shippo provides managed accounts for USPS, UPS, FedEx, DHL Express by default). See references/tool-reference.md for the full tool catalog.
Purchases are live: label purchases charge the authorized Shippo account for real. Confirm carrier, service, and cost with the user before any purchase.
Response envelope: The MCP wraps most API responses in a Speakeasy envelope shaped like {"ContentType": "application/json", "StatusCode": , "RawResponse": {}, ". The payload field is named after the response schema on success (e.g. ParsedAddress, AddressPaginatedList, AddressValidationResultV2, AddressWithMetadataResponse, Shipment, CarrierAccountPaginatedList) and after the HTTP status code on some errors (e.g. fourHundredAndNineApplicationJsonObject for a 409, the body may be {}). To extract the payload, find the field whose key is not ContentType, StatusCode, or RawResponse, and branch on StatusCode for success vs error.
Non-envelope errors: Some failures bypass the envelope entirely and surface as an MCP-level error instead, the tool response has isError: true with a single text block containing a plaintext message like Unexpected API response status or content-type: Status 404 Content-Type application/json Body: {"detail":"Not found."}. Argument-validation failures come back as JSON-RPC error code -32602. Handle both paths when reporting errors to the user.
Latest Shippo API version: 2018-02-08. Send via the Shippo-API-Version header.
The hosted Shippo MCP at https://mcp.shippo.com exposes exactly 4 tools (a meta-API), not the underlying operations directly:
shippo_list_tools: discover which operation you need.shippo_describe_tool: get that operation's input schema.shippo_read_execute_tool: run a read (lists, gets, lookups).shippo_write_execute_tool: run a write or mutation (creates, purchases, voids).Every operation name in this skill (ValidateAddress, CreateShipment, CreateTransaction, GetTrack, etc.) is invoked through these wrappers, never called as a tool on its own. Standard discovery pattern: shippo_list_tools to find the operation, then shippo_describe_tool for its schema, then shippo_read_execute_tool or shippo_write_execute_tool to run it. The read/write split lets approval policies gate mutations separately. In the Claude apps these 4 tools may be deferred (loaded on demand), so an initial "tool has not been loaded yet" is normal: discover via the wrappers rather than guessing operation names.
| Building… | Recommended primitive | See |
|---|---|---|
| ---------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------- |
| Checkout flow with live shipping rates | Rates at Checkout | Rate Shopping (+ shippo/references/rate-shopping-guide.md) |
| Single label purchase | Shipments + Transactions | Label Purchase |
| Bulk label generation from CSV | Batches + Manifests | Batch Shipping (+ shippo/references/csv-format.md) |
| Track packages across carriers | Tracking + webhooks | Tracking |
| Validate user addresses before save | Addresses v2 | Address Validation (+ shippo/references/address-formats.md) |
| Analyze shipping spend / optimize carriers | Shipments + Transactions list | Shipping Analysis |
| International shipments | Customs Items + Declarations | Label Purchase (+ shippo/references/customs-guide.md + shippo/references/international-shipping.md) |
Read the relevant skill or reference before answering integration questions or writing code.
CreateTransaction. Show carrier/service/cost/eta and require explicit user confirmation."10", never 10.The MCP wraps responses in a Speakeasy envelope. Some failures bypass the envelope. See shippo/references/response-envelope.md and shippo/references/error-reference.md for parsing logic and error-handling patterns.
The hosted MCP at https://mcp.shippo.com uses per-user Shippo OAuth. You authorize once through Shippo (in Claude Code, run /mcp and sign in), and the session refreshes automatically. There is nothing to copy or configure. Once you are connected, the workflow guidance below is unchanged.
"Token does not exist": the credential is invalid, revoked, or for a different account. Re-authorize the Shippo OAuth session."Authentication credentials were not provided": no credential reached Shippo. The OAuth session is not authorized yet, or it has expired. Re-authorize the Shippo OAuth session.Label and batch purchases charge the authorized Shippo account for real money. Before any CreateTransaction or PurchaseBatch, show the carrier, service level, cost, and ETA, and get explicit user confirmation. Do not proceed without it.
(Once Mintlify migration completes, .md URL suffixes will provide raw markdown access for AI agents.)
The Shippo API uses v1 field names for address components in most endpoints (including CreateShipment). Always use:
| Field | Description | Example |
|---|---|---|
| --- | --- | --- |
name | Full name | Jane Smith |
street1 | Street address line 1 | 731 Market St |
street2 | Street address line 2 (optional) | Suite 200 |
city | City | San Francisco |
state | State or province | CA |
zip | Postal code | 94103 |
country | ISO 3166-1 alpha-2 country code | US |
email | Email (required for international senders) | jane@example.com |
phone | Phone (required for international senders) | +1-555-123-4567 |
Note: CreateAddress and ValidateAddress take the v2 field names (address_line_1, city_locality, state_province, postal_code), but when passing addresses inline to CreateShipment, you must use the v1 names above.
street1, city, state, zip, country (ISO 3166-1 alpha-2).CreateAddress with the address fields. This creates the address and returns an object ID.ValidateAddress with the address fields to get validation results. Note: this endpoint takes address fields as query parameters, not an object ID.analysis.validation_result.value in the response. Values: "valid", "invalid", or "partially_valid" (address found with corrections applied). Check analysis.validation_result.reasons for details.changed_attributes). Note analysis.address_type ("residential", "commercial", or "unknown") -- residential classification affects carrier surcharges.recommended_address, present it to the user.partially_valid: show what was corrected and ask the user to confirm the corrections are acceptable.ParseAddress with the raw string (e.g., "123 Main St, Springfield IL 62704").address_line_1, city_locality, state_province, postal_code.country. You must ask the user for the country or infer it, then add it before proceeding.CreateAddress then ValidateAddress (follow the structured address workflow above from step 2).country field. Do not guess.There is no batch validation endpoint. Call CreateAddress per address. Track results (row number, valid/invalid, corrections, errors, residential classification) and report a summary when done. For 50+ addresses, set expectations about processing time and provide progress updates.
Call ValidateAddress with the address fields. This endpoint validates by address fields, not by object ID.
If CreateAddress returns a "Duplicate address" error, the address already exists in the account. Retrieve it via ListAddresses or proceed directly to validation.
Validate an address:
CreateAddress (saves address) + ValidateAddress (validates with same fields)
Parse then validate:
ParseAddress -> add country -> CreateAddress + ValidateAddress
"10" not 10).ValidateAddress (see Address Validation).CreateShipment with address_from, address_to (as inline address objects using v1 field names -- street1, city, state, zip, country -- not object IDs), and parcels.rates array contains available options. Present a table: carrier, service level, price, estimated days.object_id. To buy a label, pass the chosen rate's object_id to the purchase flow (see Label Purchase); you do not re-send the address or parcel.Rates expire after 7 days. If a user tries to purchase a rate that was retrieved more than 7 days ago, create a new shipment to get fresh rates.
Map user requests: "overnight" = estimated_days 1, "2-day" = estimated_days <= 2, "within N days" = estimated_days <= N. Filter the rates array accordingly. If nothing matches, show the fastest available option.
Some carriers may return international rates without a customs declaration, but others will not. If no rates are returned, try attaching a customs declaration to the shipment. Some carriers also require a phone number on the destination address for international rate retrieval. Inform the user that customs will be required at label purchase time regardless. See references/customs-guide.md for customs details.
Call CreateLiveRate instead of CreateShipment. Accepts address_from, address_to, and line_items (each with title, quantity, total_price, currency, weight, weight_unit).
Call ListShipmentRatesByCurrencyCode with the preferred ISO currency code (USD, EUR, GBP, CAD, etc.).
Identify the cheapest (lowest amount), fastest (lowest estimated_days), and best-value options from the rates array. These are not API fields -- compute them by sorting the rates array yourself. State the trade-off: "Option A is $X cheaper but takes Y more days than Option B."
ListCarrierAccounts if needed.Get rates:
(optional) ValidateAddress (x2) -> CreateShipment (with inline addresses) -> read rates array
Label purchases charge the authorized Shippo account for real. Before purchasing, explicitly state "this will charge your Shippo account" with the carrier, service, and cost, and require the user to acknowledge. Do not purchase without that confirmation.
Before every call to CreateTransaction, summarize the following and ask the user for explicit confirmation:
Do not proceed without explicit user confirmation.
ValidateAddress (see Address Validation).CreateShipment with address_from, address_to (as inline address objects using v1 field names -- street1, city, state, zip, country), parcels, and async: false.CreateTransaction with: rate (selected rate object_id), label_file_type (default PDF_4x6), async: false.status:SUCCESS: return tracking_number, label_url (display the COMPLETE URL -- S3 signed URLs break if truncated), and tracking_url_provider.QUEUED/WAITING: poll GetTransaction until resolved.ERROR: report messages from the messages array.All domestic steps apply, plus customs handling before shipment creation. See references/customs-guide.md for the full customs workflow.
ValidateAddress. Sender must include email and phone. Ask if missing.CreateCustomsItem per item (description, quantity, net_weight, mass_unit, value_amount, value_currency, origin_country, tariff_number). Alternatively, you can skip this step and pass inline item objects directly in the declaration (step 3).CreateCustomsDeclaration with contents_type, non_delivery_option, certify: true, certify_signer, and the items (either object_ids from step 2, or inline item objects). See references/customs-guide.md for field details.CreateShipment with all standard fields plus customs_declaration (the declaration object_id).Use this to determine the correct contents_type value:
| Scenario | Value |
|---|---|
| --- | --- |
| Selling to the recipient (commercial sale) | MERCHANDISE |
| Sending a free gift | GIFT |
| Sending a product sample | SAMPLE |
| Paper documents only | DOCUMENTS |
| Customer returning a purchased item | RETURN_MERCHANDISE |
| Charitable donation | HUMANITARIAN_DONATION |
| None of the above | OTHER (requires contents_explanation) |
The incoterm field on the customs declaration controls who pays duties and taxes:
DDU (Delivered Duty Unpaid) -- recipient pays duties at delivery.DDP (Delivered Duty Paid) -- seller covers all duties and taxes.FCA (Free Carrier) is available for advanced trade scenarios.If the user does not specify, default to DDU for standard e-commerce shipments.
To generate a return label, swap address_from and address_to so the original recipient becomes the sender and the original sender becomes the recipient. All other steps (shipment creation, rate selection, label purchase) remain the same.
Default to PDF_4x6 unless the user specifies otherwise. Supported formats: PDF_4x6, PDF_4x8, PDF_A4, PDF_A5, PDF_A6, PDF, PDF_2.3x7.5, PNG, PNG_2.3x7.5, ZPLII.
When purchasing a label via CreateTransaction, the following options may be set on the shipment or rate:
signature_confirmation on the shipment's extra field. Values: STANDARD, ADULT, CERTIFIED, INDIRECT, CARRIER_CONFIRMATION.insurance on the shipment's extra field with amount, currency, and provider.saturday_delivery to true in the shipment's extra field. Only supported by certain carriers and service levels.metadata on the transaction for order numbers or internal references.If the user already has a rate object_id: optionally call GetRate to confirm details, then confirm purchase (see Purchase Confirmation Gate), then call CreateTransaction directly.
Call CreateRefund with the transaction object_id.
Refund limitations: Void/refund eligibility depends on carrier and timing. Not all labels can be refunded after purchase. If CreateRefund fails, advise the user to contact Shippo support.
Domestic label:
(optional) ValidateAddress (x2) -> CreateShipment (with inline addresses) -> user picks rate -> confirm -> CreateTransaction
International label:
(optional) ValidateAddress (x2) -> CreateCustomsItem (per item) -> CreateCustomsDeclaration -> CreateShipment (with inline addresses + customs_declaration) -> user picks rate -> confirm -> CreateTransaction
Return label:
Same as domestic/international, but swap address_from and address_to.
Order-to-label:
CreateOrder -> CreateShipment (using order address/item data) -> user picks rate -> confirm -> CreateTransaction -> packing slip (REST fallback, see below)
Use orders to represent e-commerce fulfillment requests. An order captures the shipping address, line items, and totals -- then feeds into the standard label purchase workflow.
CreateOrder: Create an order with line items, shipping address, and order details.GetOrder: Retrieve an order by its object_id.ListOrders: List all orders.GET /orders/{ORDER_ID}/packingslip/ (returns a 24-hour S3 PDF link). Fall back to a direct REST call, or advise the user to use the Shippo dashboard until the MCP gap is closed.CreateOrder with the shipping address, line items (title, quantity, sku, total_price, etc.), and order-level fields.CreateShipment, then follow the standard label purchase flow (rate selection, confirmation, CreateTransaction).usps, ups, fedex, dhl_express). See references/carrier-guide.md for tracking number format hints per carrier. If uncertain, ask the user.GetTrack with carrier and tracking_number.tracking_status (status, status_details, status_date, location), tracking_history, eta.substatus object with code, text, and action_required (boolean). Include substatus details when presenting tracking history -- these provide more specific information about what happened at each step.See references/carrier-guide.md for carrier-specific status nuances. Standard values:
| Status | Meaning |
|---|---|
| --- | --- |
| PRE_TRANSIT | Label created, carrier has not received the package |
| TRANSIT | Package is in transit |
| DELIVERED | Delivered |
| RETURNED | Being returned or returned to sender |
| FAILURE | Delivery failed |
| UNKNOWN | No tracking information from carrier |
The eta field is provided by most major carriers (USPS, UPS, FedEx, DHL Express) but availability is carrier-dependent, it may be null for regional carriers or for shipments before the carrier has finalized routing. Treat absence as informational, not as an error condition.
Call ListTransactions. Filter for object_status: SUCCESS. Each successful transaction has tracking_number and carrier info. Then call GetTrack for selected items.
createWebhook with url and event: track_updated.CreateTrack with carrier and tracking number to register a specific shipment for push updates.Track a package:
GetTrack with carrier + tracking number
Find past shipment tracking:
ListTransactions -> filter SUCCESS -> GetTrack
Batch purchases charge the authorized Shippo account for real. Before PurchaseBatch, show the shipment count, carrier/service, and estimated total cost, and require explicit user confirmation.
Before every call to PurchaseBatch, summarize the following and ask the user for explicit confirmation:
Do not proceed without explicit user confirmation.
See references/csv-format.md for the column specification.
references/customs-guide.md. Use correct customs enum values: RETURN_MERCHANDISE (not RETURN) for returned goods, HUMANITARIAN_DONATION (not HUMANITARIAN) for charitable donations.batch_shipments array with inline address and parcel objects per row.CreateBatch with the array.GetBatch until status changes from VALIDATING to VALID. See Polling Intervals below.PurchaseBatch to buy labels for all valid shipments.GetBatch until status changes from PURCHASING to PURCHASED. See Polling Intervals below.For batches over 500 shipments, consider splitting into multiple batches. Large batches take longer to validate and purchase, and a single failure can be harder to diagnose.
GetBatch with the batch object_id.CreateShipment per shipment to get rate quotes (see Rate Shopping).batch_shipments with servicelevel_token per item.AddShipmentsToBatch (before purchase only). Note: adding an invalid shipment will change the entire batch status to INVALID. Check per-shipment statuses after adding.RemoveShipmentsFromBatch (before purchase only).carrier_account (object_id), shipment_date (YYYY-MM-DD, default today), address_from (pickup address).CreateManifest.GetManifest until status is SUCCESS or ERROR.CSV batch:
Parse CSV -> CreateCustomsDeclaration (international rows) -> CreateBatch -> poll GetBatch -> confirm -> PurchaseBatch -> poll GetBatch
Manifest:
CreateManifest (with transaction object_ids) -> poll GetManifest
ListCarrierAccounts to see configured carriers.CreateShipment per destination to collect rates. Creating shipments is free; only CreateTransaction costs money.analysis/ directory (markdown report + CSV). Columns: Route, Destination, Carrier, Service, Cost, Currency, EstimatedDays, Zone.ListCarrierParcelTemplates and ListUserParcelTemplates for flat-rate and saved templates. See references/rate-shopping-guide.md for dimensional weight and flat-rate guidance.CreateShipment per profile on the same route.references/carrier-guide.md for carrier-specific weight limits and surcharges.CreateShipment for the route.rates array by provider.ListShipments and ListTransactions to get past activity.GetTrack to check actual vs. estimated delivery times.Write reports to the analysis/ directory. Create it if it does not exist. Include both markdown and CSV. CSV must have a header row. Markdown must include a timestamp and input parameters.
Cost analysis:
ListCarrierAccounts -> CreateShipment (per destination) -> read rates arrays -> write report
Carrier comparison:
CreateShipment -> group rates by provider -> summarize
Historical review:
ListShipments + ListTransactions -> cross-reference -> GetTrack (sample) -> write report
The Shippo MCP is hosted at https://mcp.shippo.com. It is OAuth-only and auto-updates server-side, so there is nothing to install or upgrade on your side. This skill covers what stays your responsibility: API version awareness, webhook payload versioning, and troubleshooting the hosted session.
The current Shippo API version is 2018-02-08. Shippo uses a single long-lived API version, and the hosted server manages it for you server-side. You do not set the Shippo-API-Version header yourself when going through the hosted MCP.
What backward-compatibility means in practice:
Shippo API changes are tracked in the API changelog. As of 2026-06, no recent breaking changes affect the workflows covered by this skill set.
Webhook events can include new fields without bumping the API version. To handle them gracefully:
track_updated, transaction_created, transaction_updated, etc.).Shippo-Signature header per webhook docs.401 or 403 errorsThe OAuth session has expired or is not authorized. Re-authorize the Shippo OAuth session: in Claude Code, run /mcp and sign in again.
The hosted server auto-updates, so the tool catalog can shift without any action on your side. Re-list the current tools via shippo_list_tools to see what is available now.
Most likely the object does not exist on the authorized account, or it belongs to a different account. Confirm you are signed in to the account that owns the object (re-authorize via /mcp if needed).
Before making a change to a production integration:
shippo_list_tools after an update to catch renamed or added operations."10" not 10).carrier-accounts-list.https://mcp.shippo.com, authenticated by your per-user Shippo OAuth token. The server forwards each call to api.goshippo.com on your behalf. Nothing runs or is stored locally.共 5 个版本
暂无安全检测报告