Ads Uploader

Documentazione

MCP, CLI e API

Configurazione via MCP

MCP (Model Context Protocol) è un modo standard con cui le app di IA usano strumenti esterni. Il server MCP di Ads Uploader dà al tuo agente IA le stesse funzioni che usa il CLI: esplorare account, campagne, gruppi di inserzioni e annunci, caricare media, salvare preset, lavorare con i build salvati, vedere l'anteprima di un build e creare annunci. Se conosci l'applicazione web o il CLI, gli strumenti MCP seguono esattamente lo stesso flusso di lavoro.

L'accesso all'MCP è riservato ai piani a pagamento e non è disponibile durante la prova. Usa lo stesso account e la stessa connessione Meta dell'applicazione web e del CLI, e viene disattivato ogni volta che l'accesso al CLI viene disattivato per un account.

CLI o MCP?

Entrambi girano sulla stessa infrastruttura, quindi è una scelta di flusso di lavoro, non di funzionalità. Il CLI è la scelta migliore quando vuoi gestire tutto il tuo lavoro tramite un agente IA: caricamenti in blocco dal disco, lanci ripetuti e build completi assemblati dal terminale.

L'MCP è più adatto a lavori mirati in cui l'applicazione web resta parte del processo. Per esempio:

  • Caricare e controllare tutti i tuoi media nell'uploader web, poi passare il build all'agente per un singolo passaggio
  • Far configurare all'agente il gruppo di inserzioni
  • Far scrivere o riscrivere all'agente il testo dei tuoi annunci
  • Abbinare il copy degli annunci da un foglio di calcolo ai nomi dei file dei tuoi caricamenti

I build salvati collegano i due. L'uploader web, il CLI e l'MCP usano tutti gli stessi riferimenti ai build, così un build può passare dall'uno all'altro senza che nessuno debba riscriverlo. Vedi Build salvati.

Collega un'app di chat (Claude, ChatGPT, Cursor)

Usa il server ospitato quando lavori da un'app di chat e vuoi accedere tramite il browser. Aggiungi questo URL come connettore personalizzato nella tua app:

https://adsuploader.com/api/mcp

Per esempio, in Claude vai su Settings > Connectors > Add custom connector. Anche ChatGPT e Cursor supportano connettori MCP personalizzati. Dopo averlo aggiunto, completa l'accesso ad Ads Uploader e la schermata di consenso nel browser. Non c'è nessun token da copiare o incollare. Per verificare che funzioni, chiedi al tuo agente di elencare i tuoi account pubblicitari.

Collega con una chiave API (per i tuoi agenti e script)

L'accesso OAuth è il modo normale per collegare un'app di IA come Claude o ChatGPT. Usa una chiave API per connessioni di lunga durata dei tuoi agenti e script quando l'accesso tramite browser non è pratico. Creala in Account > MCP, CLI & API. Ogni chiave è destinata a una persona. Vedi Chiavi API per la creazione, l'uso e la revoca.

Invia Authorization: Bearer adk_... a https://adsuploader.com/api/mcp. Per un client MCP che supporta header personalizzati, la configurazione può essere così:

{
  "mcpServers": {
    "ads-uploader": {
      "url": "https://adsuploader.com/api/mcp",
      "headers": { "Authorization": "Bearer adk_..." }
    }
  }
}

Collega un agente di programmazione (Claude Code, Claude Desktop, Cursor)

Gli agenti di programmazione possono usare lo stesso server ospitato. In Claude Code, esegui:

claude mcp add --transport http ads-uploader https://adsuploader.com/api/mcp

In altri agenti, aggiungi https://adsuploader.com/api/mcp come server MCP remoto e completa l'accesso nel browser quando ti viene chiesto. Se il tuo agente supporta solo server locali (stdio), collegati al server ospitato con npx mcp-remote https://adsuploader.com/api/mcp.

Esegui il server sul tuo computer

Puoi anche eseguire il server MCP in locale. È utile quando vuoi che l'agente carichi i file direttamente dal tuo disco. Richiede Node.js 18 o successivo:

npm install -g @adsuploader/cli @adsuploader/mcp
ads login

Poi aggiungi il comando ads-mcp alle impostazioni MCP del tuo agente:

{
  "mcpServers": {
    "ads-uploader": {
      "command": "ads-mcp"
    }
  }
}

Il server locale usa l'accesso salvato da ads login. Non apre un browser da solo, quindi esegui di nuovo ads login quando quell'accesso scade (dopo 30 giorni).

Cosa può fare il tuo agente

Il server dà al tuo agente gli strumenti per l'intero flusso di lavoro di un build. Descrivi quello che vuoi in linguaggio naturale e l'agente chiama gli strumenti per te.

AreaCosa può fare l'agente
IdentitàConfermare con quale utente Ads Uploader ha effettuato l'accesso prima di modificare qualsiasi cosa
AccountElencare i tuoi account pubblicitari Meta e passare l'accountId corretto a ogni chiamata
EsplorazioneElencare campagne, gruppi di inserzioni, annunci e Pagine; leggere tutte le impostazioni creative di un annuncio
TargetingCercare chiavi delle città, codici postali e ID del targeting dettagliato con ads_search_targeting, così non deve mai indovinarli
PresetElencare i preset API e i preset di testo salvati, leggere un preset con ads_get_preset e salvare un annuncio esistente come preset
BuildElencare, leggere, salvare, aggiornare ed eliminare build salvati, oppure copiarne uno in una nuova bozza con ads_fork_build così l'originale resta com'è. Ogni build ha un link che lo apre nell'uploader web.
MediaCaricare immagini e video nel tuo account pubblicitario ed elencare i batch di caricamento recenti
AnteprimaMostrare esattamente cosa verrebbe creato prima di creare qualsiasi cosa
CreazioneCreare annunci da un preset, da un annuncio copiato, da un build salvato o da una specifica completa, poi seguire o annullare il job
Duplicazione tramite ID del postVedere l'anteprima di una duplicazione tramite ID del post con ads_duplicate_by_post_preview, avviarla con ads_duplicate_by_post e seguirla con ads_get_duplication

Prima l'anteprima. Sul server ospitato, ads_create segue il job per circa 60 secondi. Se il job è ancora in corso, restituisce il riferimento del job e il tuo agente continua a controllarlo con ads_get_job. Il job gira sul server e non dipende dal fatto che la connessione resti aperta. Sul server locale, ads_create può seguire il job per un massimo di 30 minuti.

Lavora con i build salvati

I build si salvano automaticamente mentre lavori nell'uploader web. Ognuno ha un riferimento permanente (build_...), mostrato in fondo al passaggio di configurazione e nella finestra Saved Builds. Dai quel riferimento al tuo agente e potrà leggere esattamente la configurazione che vedi, modificarla e salvarla di nuovo nello stesso build.

Se il build è aperto nell'uploader, l'uploader rileva la modifica salvata e la applica per te quando non hai modifiche non salvate. Puoi anche cliccare il pulsante di aggiornamento accanto al riferimento del build per controllare subito. Se hai modifiche non salvate quando arriva una modifica esterna, l'uploader ti chiede se caricare le modifiche esterne o mantenere le tue, così nessuna delle due versioni va persa. Se la scheda è chiusa, chiedi all'agente il link del build.

Gli editor di testo per annuncio e per gruppo di inserzioni dell'uploader web hanno pulsanti Claude e ChatGPT che aprono una chat con il riferimento del tuo build già inserito, così passare il lavoro sui testi richiede un solo clic. Funziona anche al contrario: chiedi all'agente di salvare il suo lavoro come build, poi apri il link per controllare tutto nel browser prima che venga creato qualsiasi annuncio.

Carica i media

Il modo in cui i file arrivano al tuo account pubblicitario dipende da dove gira il server:

  • Server ospitato (app di chat e agenti di programmazione che usano l'URL ospitato): dai all'agente link di download HTTPS pubblici, un link pubblico a un file di Google Drive o un link pubblico a una cartella di Drive. Ads Uploader scarica ed elabora i file in background, così i dati dei file non passano mai dalla chat.
  • Server locale (ads-mcp): l'agente può anche caricare file direttamente dal tuo disco. Per le cartelle sul tuo computer puoi anche usare il CLI con ads upload.

Dopo l'avvio di un caricamento da link o da Drive, l'agente lo controlla con ads_get_upload. Quando finisce, il risultato include il riepilogo del batch usato per le anteprime e la creazione degli annunci. Per fermare un'importazione indesiderata, l'agente chiama ads_cancel_job; i file già completati restano utilizzabili e il risultato mostra quanti sono stati completati, non sono riusciti o sono stati saltati. Le immagini con nome *_thumbnail vengono associate al video corrispondente come miniature personalizzate invece di essere contate come media separati, quindi il totale dei media di una cartella può essere inferiore al numero dei suoi file. Se Google blocca per un po' l'importazione di una cartella, il risultato indica cosa è stato completato, cosa non è riuscito e cosa è stato saltato, così l'agente può dirti di riprovare più tardi.

I link di Drive devono essere condivisi come Anyone with the link (Viewer). I file privati di Drive sono una funzione dell'uploader web.

Le immagini piccole si possono anche inviare inline (fino a 10 MB in totale per chiamata). Un agente di programmazione in grado di inviare direttamente i dati dei file può chiedere il vecchio percorso di caricamento diretto, che carica sullo storage di Ads Uploader. Solo quel percorso richiede l'accesso in uscita al nostro host di caricamento. Se il tuo agente gira in una sandbox di rete, consenti *.adsuploader.com nella allowlist di rete o della sandbox del tuo agente. La risposta del caricamento indica l'host esatto in allowlistHost; se mai fosse diverso, fidati della risposta.

Limiti

  • 50 file per chiamata di caricamento. Dividi i caricamenti più grandi in più chiamate.
  • Limiti di frequenza. Le chiamate sono limitate per utente e per tipo di chiamata su un minuto mobile (per esempio, 120 chiamate agli strumenti MCP al minuto, e 20 al minuto per ogni tipo di chiamata di elenco o di anteprima). Un uso normale resta molto al di sotto di questi limiti. Se il tuo agente raggiunge un limite, riceve un errore "rate limit" e deve aspettare prima di riprovare.
  • Un solo job di creazione annunci alla volta per utente, come per il CLI.

Autenticazione e accesso

Il server ospitato ti fa accedere con OAuth, il flusso standard "accedi e approva". Il token di accesso che rilascia dura un'ora. Se la tua app supporta i refresh token, riceve anche un refresh token che dura 30 giorni e lo usa per rinnovare il token di accesso in background, così non devi accedere a ogni sessione. Altrimenti, l'app ti chiede di accedere di nuovo quando il token scade.

L'accesso segue il tuo account: è riservato ai piani a pagamento, e disattivare l'accesso al CLI per un account rimuove subito anche il suo accesso all'MCP.

Annunci di partnership

Gli strumenti MCP ads_preview e ads_create accettano le stesse specifiche di partnership del CLI:

  • Con i tuoi media: aggiungi profile.partnership.enabled: true con gli ID del tuo partner a una normale specifica per media. Puoi impostare un partner diverso per ogni annuncio o per ogni gruppo di inserzioni.
  • Da post Instagram esistenti: importa un post autorizzato con mediaItems[].kind: "partnershipPost".

L'anteprima mostra il partner, l'approvazione e la modalità dell'intestazione di ogni annuncio, raggruppati per gruppo di inserzioni. Per le strutture complete della specifica e i limiti, vedi Annunci di partnership con i tuoi media e Specifica per annunci di partnership da post Instagram esistenti.

Product Showcase

Product Showcase mostra prodotti di un catalogo sotto un annuncio con una singola immagine o un singolo video. Gli annunci di catalogo completo (dinamici/DPA) non sono ancora supportati.

Gli ID devono essere stringhe di cifre. Le raccomandazioni richiedono campagne Vendite (OUTCOME_SALES); la selezione manuale di catalogo e set funziona anche con altri obiettivi. Product Showcase non è disponibile per caroselli, formati flessibili, multimedia, post esistenti e annunci Partnership.

Consulta cataloghi e set, quindi richiedi una raccomandazione:

  • ads_list_catalogs({ accountId })
  • ads_list_product_sets({ accountId, catalogId, productSetId? })
  • ads_get_product_showcase_recommendation({ accountId, adUrl, pageId?, pixelId? })

Create e Preview accettano productShowcase: { enabled?, catalogId?, productSetId?, useRecommendation? }; enabled è true per impostazione predefinita. Omettendo il campo si eredita la creatività originale. RECOMMENDED usa la scelta Meta (choiceSource: "DEFAULT"); MUST_PICK richiede un ID candidato come productSetId ("MANUAL"). MANUAL richiede catalogo e set. Una scelta diversa verificata usa "MANUAL".

Flag Create e Preview: --product-showcase <on|off|recommended>, --catalog <id>, --product-set <id>. Solo ID significa on; recommended imposta useRecommendation: true. Off imposta { enabled: false }, non ammette ID e conserva il set dell’annuncio originale.

Preview restituisce productShowcase con enabled, ID, nome facoltativo, choiceSource e source (recommendation, manual, source_ad), oppure null. Le raccomandazioni sono di sola lettura. Test Mode richiede ID quando attivo, non consulta cataloghi e segnala la mancata verifica. Le scelte salvate nell’interfaccia vengono convertite; i valori predefiniti vengono ricontrollati al lancio.

←
Previous
Riferimento completo del CLI
Next
Ads Insights (Beta)
→