YunExpress to MCP: Cross-Border Shipments, Freight Quotes, Labels and Tracking in any AI Agent

💡 No install? Use cloud.anythingmcp.com directly. Sign in, click Connectors → YunExpress, paste your credentials, mint an MCP API key and you're done. No Docker, no git clone, no local server.

YunExpress

YunExpress (云途物流) OMS API: destination countries, shipping methods and goods types, freight quotes, shipment orders with tracking numbers, labels, last-mile carriers, tracking events and charged fees, weight changes and interceptions. Deleting orders installs switched off.

Setup

Setting up takes about 5 minutes. You need a YunExpress customer account with API access.

1. Sign in to the YunExpress customer center (www.yunexpress.cn or your YunExpress customer portal) and open the API section. Note your customer code (客户编号, e.g. C12345) and the API secret (API密钥); apply for the key there if there is none yet.
2. YunExpress authenticates with Authorization: Basic <token>, where the token is the Base64 of customer code, an ampersand and the API secret (an ampersand, not a colon). Compute it once on your computer, for example printf '%s' 'C12345&YourApiSecret' | base64, and paste only the result into YUNEXPRESS_API_TOKEN. It is stored encrypted.
3. Install the connector and run yunexpress_list_countries: it lists the destination countries and confirms the token.

Which API: the connector uses the YunExpress OMS API (version 1.4.x) on http://oms.api.yunexpress.com. That host answers over plain HTTP only. YunExpress also runs a newer open platform (openapi.yunexpress.cn) that signs every request with a timestamp and an OAuth token; this connector does not use it.

What it reads: destination countries with their two-letter codes; the shipping methods (logistics products) of your account with code, Chinese and English name and whether they are tracked, optionally only those serving one country; goods types such as general goods or goods with batteries; freight quotes per shipping method with base, registration, fuel and other fees, total, currency, billable weight and delivery days (yunexpress_get_price_quote, with postal code for remote-area surcharges); shipment orders with waybill number, customer order number, tracking number, method, status, weights, receiver, customs lines and fees; the sender address of an order; tracking with package state, tracking status, last-mile carrier, proof of delivery and events (yunexpress_get_tracking follows your tracking display settings, yunexpress_get_full_tracking returns the whole history where the method supports it); the last-mile carrier and its number; the fees actually charged once YunExpress has weighed and billed a waybill.

Ship a parcel: the AI checks the methods for the country and the goods type, gets a quote, then calls yunexpress_create_orders with 1 to 10 orders per call. Each result has Success, WayBillNumber, TrackingNumber and TrackType (1 tracking number available, 2 pending, 3 none). When the tracking number is pending, yunexpress_get_tracking_numbers fetches it later by customer order number (results are cached for 30 minutes). yunexpress_get_labels returns the labels of up to 50 orders as a temporary PDF URL.

What it writes: yunexpress_create_orders books real shipments, yunexpress_update_weight changes the forecast weight before YunExpress weighs the parcel, and yunexpress_intercept_order asks YunExpress to stop a parcel, with a reason. Before each write the AI shows the orders (receiver, method, weight, customs declaration) and waits for your yes. After an unclear timeout it reads the order with yunexpress_get_order before trying again, so nothing is booked twice.

Switched off at install: yunexpress_delete_order, which removes an order YunExpress has not received yet and cannot be undone. An administrator switches it on when the team needs it.

Numbers and units: weights in kg (up to 3 decimals), dimensions in whole cm, declared values (UnitPrice) per unit in the stated CurrencyCode. OrderNumber takes the waybill number, your customer order number or the tracking number; for intercept and delete, OrderType says which one (1 waybill, 2 customer order, 3 tracking number). Package states: 0 unknown, 1 submitted, 2 in transit, 3 delivered, 4 received, 5 cancelled, 6 delivery failed, 7 returned. Tracking status: 0 not found, 10 pre-advice, 20 in transit, 30 ready for pickup, 40 failed, 50 delivered, 60 exception, 80 unknown, 90 returned, 100 cancelled.

Limits: there is no paging; lists come in one answer. Order creation takes 10 orders per call, labels 50. When YunExpress answers code 10000 the request limit is reached: wait a moment.

Common errors: every answer has Code (0000 is success), Message, the data in Item or Items and a RequestId to quote to YunExpress support. HTTP 421 with ResultCode 401, or code 1002 or 1003, means the token is wrong: recompute it from customer code and secret with the ampersand. 1004 is a parameter error, 1006 no data, 1011 partial success, 2004 a duplicate customer order number, 2005 an existing order, 2006 no tracking number for this method, 2009 a weight that is not positive, 2010 a method that does not serve the destination, 9999 a platform error.

The connector does not use the YunExpress open platform and does not manage your account, invoices or payments: the only cost data it reads are quotes and the fees charged per waybill.

Prerequisites: YUNEXPRESS_API_TOKEN

Install the connector locally

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Open http://localhost:3000/connectors/store, pick YunExpress and paste in the env vars listed under Prerequisites.

Available tools

Example prompts

• "Which YunExpress shipping methods serve Germany, and which of them are tracked?"
• "Quote a 0.35 kg parcel of 20 x 15 x 5 cm to France with a battery, per method with total and delivery days."
• "Create a YunExpress order for SO-1042 to Anna Muster in Berlin with method THPHR. Show me receiver, weight and customs lines first."
• "Where is the parcel with tracking number YT2430012345678901, and who delivers the last mile?"
• "Get the labels of today's orders SO-1040 to SO-1045 as one PDF."

Next steps

• Connect to Claude
• Connect to ChatGPT