Come collegare YunExpress a Cursor via MCP

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → YunExpress, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

YunExpress + Cursor

API OMS di YunExpress (云途物流): paesi di destinazione, metodi di spedizione e tipi di merce, preventivi di nolo, ordini di spedizione con numeri di tracking, etichette, corrieri dell'ultimo miglio, eventi di tracking e costi addebitati, modifiche di peso e intercettazioni. La cancellazione degli ordini è disattivata all'installazione.

Prerequisiti

Le istruzioni di setup complete sono incluse nel connettore stesso (visibili nello store quando lo selezioni). Le variabili d'ambiente richieste sono:

YUNEXPRESS_API_TOKEN

Step 1 — Ottieni le credenziali

La configurazione richiede circa 5 minuti. Ti serve un account cliente YunExpress con accesso API.

1. Accedi al centro clienti YunExpress (www.yunexpress.cn o il tuo portale clienti YunExpress) e apri la sezione API. Annota il tuo codice cliente (客户编号, ad es. C12345) e l'API secret (API密钥); se non c'è ancora, richiedilo lì.
2. YunExpress si autentica con Authorization: Basic <token>, dove il token è il Base64 di codice cliente, una e commerciale e API secret (una &, non i due punti). Calcolalo una volta sul tuo computer, ad esempio con printf '%s' 'C12345&YourApiSecret' | base64, e incolla solo il risultato in YUNEXPRESS_API_TOKEN. Viene salvato cifrato.
3. Installa il connettore ed esegui yunexpress_list_countries: elenca i paesi di destinazione e conferma il token.

Quale API: il connettore usa la OMS API di YunExpress (versione 1.4.x) su http://oms.api.yunexpress.com. Questo host risponde solo in HTTP semplice. YunExpress gestisce anche una open platform più recente (openapi.yunexpress.cn) che firma ogni richiesta con un timestamp e un token OAuth; questo connettore non la usa.

Cosa legge: i paesi di destinazione con il loro codice a due lettere; i metodi di spedizione (prodotti logistici) del tuo account con codice, nome cinese e inglese e se sono tracciati, eventualmente solo quelli che servono un paese; i tipi di merce, come merce generica o con batterie; i preventivi di nolo per metodo con tariffa base, raccomandazione, carburante e altri costi, totale, valuta, peso tassabile e giorni di consegna (yunexpress_get_price_quote, con CAP per i supplementi delle aree remote); gli ordini di spedizione con numero di waybill, numero d'ordine cliente, numero di tracking, metodo, stato, pesi, destinatario, righe doganali e costi; l'indirizzo del mittente di un ordine; il tracking con stato del pacco, stato di tracking, corriere dell'ultimo miglio, prova di consegna ed eventi (yunexpress_get_tracking segue le tue impostazioni di visualizzazione, yunexpress_get_full_tracking restituisce lo storico completo dove il metodo lo supporta); il corriere dell'ultimo miglio e il suo numero; i costi effettivamente addebitati, una volta che YunExpress ha pesato e fatturato una waybill.

Spedire un pacco: l'AI controlla i metodi per il paese e il tipo di merce, chiede un preventivo e poi chiama yunexpress_create_orders con da 1 a 10 ordini per chiamata. Ogni risultato contiene Success, WayBillNumber, TrackingNumber e TrackType (1 numero di tracking disponibile, 2 in attesa, 3 nessuno). Se il numero di tracking è in attesa, yunexpress_get_tracking_numbers lo recupera più tardi tramite il numero d'ordine cliente (i risultati restano in cache per 30 minuti). yunexpress_get_labels restituisce le etichette di fino a 50 ordini come URL PDF temporaneo.

Cosa scrive: yunexpress_create_orders prenota spedizioni reali, yunexpress_update_weight cambia il peso dichiarato prima che YunExpress pesi il pacco e yunexpress_intercept_order chiede a YunExpress di fermare un pacco, con un motivo. Prima di ogni scrittura l'AI ti mostra gli ordini (destinatario, metodo, peso, dichiarazione doganale) e aspetta il tuo sì. Dopo un timeout poco chiaro rilegge l'ordine con yunexpress_get_order prima di riprovare, così nulla viene prenotato due volte.

Disattivato all'installazione: yunexpress_delete_order, che elimina un ordine non ancora ricevuto da YunExpress e non si può annullare. Un amministratore lo attiva quando il team ne ha bisogno.

Numeri e unità: pesi in kg (fino a 3 decimali), dimensioni in cm interi, valori dichiarati (UnitPrice) per unità nella CurrencyCode indicata. OrderNumber accetta il numero di waybill, il tuo numero d'ordine cliente o il numero di tracking; per intercettare ed eliminare, OrderType indica quale (1 waybill, 2 ordine cliente, 3 numero di tracking). Stati del pacco: 0 sconosciuto, 1 inviato, 2 in transito, 3 consegnato, 4 ricevuto, 5 annullato, 6 consegna fallita, 7 restituito. Stato di tracking: 0 non trovato, 10 preavviso, 20 in transito, 30 pronto per il ritiro, 40 fallito, 50 consegnato, 60 eccezione, 80 sconosciuto, 90 restituito, 100 annullato.

Limiti: non c'è paginazione; gli elenchi arrivano in una sola risposta. La creazione accetta 10 ordini per chiamata, le etichette 50. Se YunExpress risponde con il codice 10000 il limite di richieste è raggiunto: aspetta un momento.

Errori comuni: ogni risposta ha Code (0000 è successo), Message, i dati in Item o Items e un RequestId da citare al supporto YunExpress. HTTP 421 con ResultCode 401, oppure il codice 1002 o 1003, significa che il token è sbagliato: ricalcolalo da codice cliente e secret con la &. 1004 è un errore di parametro, 1006 nessun dato, 1011 successo parziale, 2004 un numero d'ordine cliente duplicato, 2005 un ordine già esistente, 2006 nessun numero di tracking per questo metodo, 2009 un peso non positivo, 2010 un metodo che non serve la destinazione, 9999 un errore della piattaforma.

Il connettore non usa la open platform di YunExpress e non gestisce il tuo account, le fatture o i pagamenti: gli unici dati di costo che legge sono i preventivi e i costi addebitati per waybill.

Step 2 — Installa l'adapter

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

Step 3 — Aggiungi il connettore in Cursor

L'URL del tuo server: in AnythingMCP apri MCP Servers → il server su cui si trova questo connettore e copia il suo URL (https://cloud.anythingmcp.com/mcp/…). Usalo ovunque questa guida mostra YOUR_SERVER_ID.

Cursor legge i server MCP da ~/.cursor/mcp.json. Aggiungi questa voce:

{
  "mcpServers": {
    "anythingmcp": {
      "url": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una chiave API MCP in AnythingMCP da MCP Servers → il tuo server → API keys e incollala al posto di YOUR_MCP_API_KEY.
2. Salva il file e riavvia Cursor.
3. Apri Cursor → Settings → MCP e verifica che anythingmcp sia elencato e connesso.
4. Inizia a chattare: l'agente ora può usare i tool di YunExpress.

Tool disponibili

Esempi di prompt

• "Quali metodi di spedizione YunExpress servono la Germania, e quali sono tracciati?"
• "Fammi un preventivo per un pacco di 0,35 kg e 20 x 15 x 5 cm con batteria verso la Francia, per metodo con totale e giorni di consegna."
• "Crea un ordine YunExpress per SO-1042 ad Anna Muster a Berlino con il metodo THPHR. Mostrami prima destinatario, peso e righe doganali."
• "Dov'è il pacco con numero di tracking YT2430012345678901, e chi fa la consegna dell'ultimo miglio?"
• "Prendi le etichette degli ordini di oggi da SO-1040 a SO-1045 in un unico PDF."

FAQ

Cursor supporta server MCP personalizzati nel piano gratuito? Sì, MCP è disponibile nei piani Hobby, Pro e Business.

Prossimi passi

• Landing del connettore
• Collegare a Claude
• Collegare a ChatGPT
• Collegare a Gemini
• Collegare a Meta Muse
• Collegare a Microsoft Copilot