Motive con Cursor via MCP: flotta e HOS

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

Motive + Cursor

Fai leggere alla tua AI la tua flotta Motive: dove si trovano ogni camion e ogni autista, contatori e violazioni delle Hours of Service, rapporti di ispezione, eventi di sicurezza, codici di guasto, miglia IFTA e rifornimenti. Solo lettura, con una API key aziendale.

Prerequisiti

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

MOTIVE_API_KEY

Step 1 — Ottieni le credenziali

La configurazione richiede circa 3 minuti. Ti serve un ruolo da admin in Motive (in passato KeepTruckin) per creare una API key aziendale nella dashboard di Motive.

1. Nella dashboard di Motive apri Admin → Developers → API Access e crea una API key aziendale (company API key). Dalle accesso in lettura (read) e gli scope per i dati che l'AI deve vedere: veicoli, posizioni, utenti, HOS, IFTA, carburante, ispezioni, eventi di sicurezza, codici di guasto, asset e gruppi. Una key si può anche limitare ad alcuni gruppi; l'AI vede allora solo quelli.
2. Copia la key dalla finestra che compare una sola volta, perché la key completa viene mostrata solo allora, e incollala in MOTIVE_API_KEY: solo la key, senza spazi né un nome di header come X-Api-Key. AnythingMCP la invia come header X-Api-Key.
3. Installa il connettore e verifica la connessione con motive_list_vehicles.

Cloud e self-hosting funzionano allo stesso modo: la API key è l'unica impostazione.

Le key scadono e non si possono modificare: una key scade secondo la scadenza scelta alla creazione, e Motive avvisa gli admin una settimana prima. I suoi scope non si possono cambiare in seguito: per accedere ad altri dati crea una nuova key e incollala in MOTIVE_API_KEY.

Id: veicoli, utenti e asset hanno id numerici di Motive. Il numero di mezzo usato da chi fa dispatching ("Truck 12") è il campo number del veicolo; motive_lookup_vehicle lo trasforma in un id. Gli autisti sono utenti con ruolo driver.

Date, fusi orari e unità: i filtri per data sono YYYY-MM-DD e la maggior parte dei report copre per default gli ultimi 7 giorni; updated_after accetta un timestamp ISO 8601. Con la maggior parte dei tool l'AI può scegliere il fuso orario dei timestamp (inviato come X-Time-Zone, per esempio America/New_York) e le unità metriche o imperiali (inviate come X-Metric-Units: chilometri e litri, oppure miglia e galloni). Indica fuso orario e unità nel prompt quando contano. Le durate delle Hours of Service in motive_list_available_time sono in secondi.

Paginazione: le liste restituiscono per default 25 record per pagina, al massimo 100 (per_page), e si sfogliano con page_no. Ogni risposta contiene pagination con per_page, page_no e total; l'AI chiede la pagina successiva finché ci sono più record di quelli già visti.

Storico delle posizioni: motive_get_vehicle_location_history legge un veicolo su un periodo di al massimo 3 mesi; tieni l'intervallo breve per una risposta leggibile. Motive accetta al massimo 10 richieste simultanee su questo endpoint.

Alcuni dati richiedono hardware o un piano: gli eventi di sicurezza della dashcam AI (uso del telefono, cintura di sicurezza, distanza ravvicinata e così via), le posizioni dal Vehicle Gateway (motive_list_vehicle_gateway_locations; i veicoli con altri ELD rispondono tramite motive_list_vehicle_locations) e le posizioni dei rimorchi con un asset gateway.

Gli account UE non sono coperti: il connettore chiama https://api.gomotive.com; gli account sulla piattaforma UE di Motive usano un host diverso.

Errori frequenti: un 401 vuol dire che Motive ha rifiutato la key: non è stata copiata per intero, è scaduta o revocata, oppure è stata incollata con il nome dell'header X-Api-Key. Un 403 vuol dire che la key è valida ma le manca lo scope per quei dati: crea una nuova key con quello scope. Un 404 vuol dire che non esiste un record con quell'id: usa l'id numerico, non il numero del veicolo o il nome dell'autista. Quando Motive limita le richieste della key, aspetta un minuto, chiedi meno pagine e riprova.

Cosa legge: veicoli con VIN, marca, modello, targa, tipo di carburante, dispositivo ELD e autista; la posizione attuale di ogni veicolo e autista e il percorso di un veicolo in un periodo; autisti, fleet user e admin; i contatori delle Hours of Service (chi può ancora guidare e per quanto), i registri giornalieri e le violazioni; viaggi IFTA e miglia per stato o provincia; rifornimenti; rapporti di ispezione (DVIR) con i loro difetti; eventi di sicurezza con stato del coaching e link ai media; codici di guasto del motore; periodi di guida, compresi uso personale (personal conveyance), spostamenti in piazzale (yard move) e guida non identificata; rimorchi e altri asset con la loro ultima posizione; e i gruppi in cui è suddivisa la flotta.

Solo lettura: ogni tool legge soltanto e nessuno è disattivato all'installazione. In Motive non cambia nulla: creare o modificare veicoli, utenti, gruppi, geofence, rifornimenti o rapporti di ispezione, inviare messaggi agli autisti, i dispatch e i comandi di immobilizzazione del motore sono esclusi.

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 Motive.

Tool disponibili

Esempi di prompt

• "Dov'è adesso Truck 12, e chi lo sta guidando?"
• "Quali autisti possono ancora guidare oggi, e per quanto tempo?"
• "Quali autisti hanno avuto frenate brusche o eventi di uso del telefono la settimana scorsa?"
• "Quali veicoli hanno rapporti di ispezione con difetti o codici di guasto aperti?"
• "Quante miglia ha percorso ogni camion per stato nell'ultimo trimestre, per la dichiarazione IFTA?"

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