News Archivi - Salvatore Salerno

Categoria: News

27 Lug

Google Ads MCP: come collegare Google Ads a Claude Code

Gli assistenti AI hanno smesso di essere semplici generatori di testo. Con il Model Context Protocol (MCP) possono collegarsi direttamente alle fonti di dati operative e interrogarle. Per chi lavora nell’advertising questo apre una possibilità concreta: analizzare i dati delle campagne in linguaggio naturale, all’interno di un unico ambiente, riducendo il tempo che separa una domanda dalla risposta utile.

Google ha rilasciato un server MCP ufficiale per Google Ads. In questa guida vediamo, passo dopo passo, come collegare Google Ads a Claude Code: le attività propedeutiche da preparare, l’installazione, l’autenticazione e le configurazioni corrette. Lungo il percorso anticipo anche le difficoltà più comuni del setup, dai permessi al token di sviluppo, così da evitartele in partenza.

Cos’è l’MCP di Google Ads e a cosa serve

MCP è lo standard aperto con cui un assistente AI si collega a una fonte esterna e ne utilizza gli strumenti. Il server MCP ufficiale di Google Ads (repository googleads/google-ads-mcp) espone a Claude tre strumenti: l’elenco degli account accessibili, la lettura dei metadati delle risorse e l’esecuzione di query GAQL, il linguaggio di interrogazione della piattaforma.

Va chiarito subito un aspetto sostanziale: il server ufficiale è di sola lettura. Non crea né modifica campagne, budget o offerte; né nella versione attuale né nella roadmap pubblica. Esistono implementazioni non ufficiali sviluppate dalla community che aggiungono operazioni di scrittura, ma il server mantenuto da Google resta circoscritto alla consultazione. Per un flusso di analisi e reportistica è esattamente il perimetro utile: si interrogano i dati senza alcun rischio di modifiche sugli account in produzione.

Il vantaggio pratico è la centralizzazione. Una sola configurazione dà accesso in linguaggio naturale ai dati di tutti gli account su cui si ha visibilità, richiamando di volta in volta l’ID del cliente.

Collegare Google Ads a Claude comporta dei costi?

La creazione e il mantenimento di un progetto Google Cloud non hanno costi. Il modello è pay-as-you-go: si paga solo per le risorse effettivamente consumate oltre le soglie del piano gratuito, e un’integrazione come questa non ne consuma. Sono gratuiti anche la generazione delle credenziali OAuth e le chiamate all’API di Google Ads.

L’unica voce che potrebbe generare un addebito è l’hosting del server su servizi di calcolo come Cloud Run o Compute Engine, scelta utile solo se si vuole tenerlo online in modo permanente. Eseguendo il server in locale insieme a Claude Code, lo scenario di questa guida, non si utilizzano risorse di Google e non si paga nulla. Il budget delle campagne, va da sé, è una spesa separata che non transita dalla fatturazione di Google Cloud.

Un progetto Google Cloud unico o uno per cliente?

Per chi gestisce più clienti la configurazione consigliata è un unico progetto Google Cloud. Si imposta la schermata di consenso OAuth una sola volta, si gestisce un solo set di credenziali e si monitorano quote e chiamate da un’unica dashboard. Il funzionamento è lineare: si autentica il proprio account — quello con visibilità sui vari account pubblicitari — e da lì si interroga ciascun cliente passando il rispettivo customer_id, senza intervenire sull’infrastruttura.

L’elemento da tenere sotto controllo con un progetto unico sono le quote API: le chiamate di tutti i clienti si sommano sullo stesso progetto. È un limite gestibile e, se necessario, si amplia richiedendo a Google un livello di accesso superiore. Progetti separati hanno senso solo di fronte a clienti che impongono un isolamento rigoroso dei dati.

Le attività propedeutiche: cosa preparare prima di installare

Qui si concentra la maggior parte del lavoro, ed è la parte che le guide più sbrigative tendono a saltare. Sono le attività che spettano a te, all’interno dei pannelli di Google, e vanno completate prima di procedere:

un account amministratore Google Ads (MCC), necessario per ottenere il developer token
il developer token con il giusto livello di accesso, dal Centro API dell’MCC
un progetto Google Cloud con la Google Ads API abilitata (da API e servizi › Libreria)
un client OAuth di tipo “App desktop” creato nel progetto, con il relativo file JSON
la schermata di consenso OAuth pubblicata in produzione

Questa è, di fatto, l’unica parte che richiede il tuo intervento diretto. L’installazione degli strumenti a riga di comando, i comandi e la registrazione del server sono operazioni che Claude Code esegue in autonomia: una volta che gli fornisci queste informazioni e concedi le autorizzazioni quando richieste, non devi digitare nulla né avere competenze da sviluppatore. I comandi che seguono sono riportati per trasparenza, così che tu sappia esattamente cosa accade.

Il developer token e l’account amministratore (MCC)

Una difficoltà frequente riguarda il developer token, il codice che abilita le chiamate all’API. Si ottiene esclusivamente dal Centro API di un account amministratore (MCC) di Google Ads, mai dai singoli account dei clienti: se gestisci gli account come amministratore ma non possiedi un MCC, la voce “Centro API” non compare affatto.

La soluzione è creare un account amministratore — operazione gratuita, immediata e che non modifica in alcun modo gli account esistenti:

vai sulla pagina Google Ads Manager Accounts e clicca su Crea un account amministratore
compila i dati base (nome, fuso orario, valuta): ottieni un pannello MCC con un ID univoco
entra in Amministrazione › Centro API: qui trovi il tuo developer token

Collegare gli account dei clienti al tuo MCC

Perché il token possa leggere i dati dei clienti, gli account vanno agganciati al nuovo MCC. La procedura è a due mani: si invia la richiesta dal manager e la si accetta dal cliente.

Prendi nota dei Customer ID a 10 cifre degli account da collegare.
Nel tuo MCC vai su Account, clicca il pulsante +, scegli Collega account esistente, incolla gli ID (anche più di uno, uno per riga) e invia la richiesta.
Entra nell’account del cliente, vai su Amministrazione › Accesso e sicurezza › Gestori, individua la richiesta in sospeso e clicca Accetta.

Verifica il livello di accesso del token

Un controllo da non saltare riguarda il livello di accesso del developer token. I token partono con l’accesso di test, che consente chiamate solo verso account di prova; per leggere i dati reali dei clienti serve almeno l’accesso di base (account di test e di produzione, fino a 15.000 operazioni al giorno), che si richiede tramite un modulo nel Centro API con un paio di giorni lavorativi di attesa. Verifica lo stato di approvazione in quella stessa pagina: se le query dovessero tornare vuote, quasi sempre è questo il motivo.

Installazione: gcloud, pipx e il server ufficiale

Servono due strumenti a riga di comando: gcloud (Google Cloud SDK) per l’autenticazione e pipx per eseguire il server. Claude li installa da sé, con il gestore di pacchetti del tuo sistema operativo, senza che tu debba intervenire.

Su macOS, con Homebrew:

brew install --cask google-cloud-sdk
brew install pipx

Su Windows, con winget (il gestore di pacchetti integrato in Windows 10 e 11):

winget install --id Google.CloudSDK -e
winget install --id Python.Python.3.13 -e   # solo se Python non è già installato
py -m pip install --user pipx
py -m pipx ensurepath

Il server ufficiale si trova nel repository googleads/google-ads-mcp e si esegue con pipx (il comando è identico sui due sistemi):

pipx run --spec git+https://github.com/googleads/google-ads-mcp.git google-ads-mcp

Alla prima esecuzione pipx scarica e prepara i componenti necessari: è normale che il primo avvio richieda qualche minuto.

Autenticazione: le due configurazioni da impostare correttamente

L’autenticazione avviene tramite Application Default Credentials (ADC). Due configurazioni vanno impostate fin dall’inizio, perché sono la causa più comune di blocchi durante il setup.

Prima: un client OAuth proprio. Lo scope di Google Ads (adwords) non è utilizzabile con il client OAuth predefinito di gcloud. Occorre quindi creare un proprio Client OAuth di tipo “App desktop” nel progetto Google Cloud (API e servizi › Credenziali › Crea credenziali › ID client OAuth) e scaricarne il file JSON.

Seconda: la schermata di consenso in produzione. Prima di autenticarti, porta la schermata di consenso OAuth in stato “In produzione” (Schermata consenso OAuth › Pubblico › Pubblica app). Se resta in modalità “Test”, l’autenticazione viene rifiutata con un errore access_denied e, anche quando funziona, il refresh token scade dopo 7 giorni; in produzione resta valido stabilmente. Per un uso personale comparirà un avviso di “app non verificata”, del tutto normale: si prosegue e si autorizza.

A questo punto Claude esegue il login, indicando il tuo file JSON e gli scope necessari:

gcloud auth application-default login \
  --client-id-file=/percorso/al/tuo/client_secret.json \
  --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform

Il browser si apre e a te resta da autorizzare l’accesso; le credenziali vengono poi salvate in locale, refresh token incluso.

Aggiungere il server a Claude Code

Con le credenziali pronte, Claude registra il server. Conviene indicare il percorso assoluto di pipx, così l’estensione lo individua a prescindere dalla configurazione dell’ambiente (nell’esempio è quello di macOS; su Windows il percorso è diverso, ma è un dettaglio che Claude risolve da sé):

claude mcp add google-ads-mcp -s user \
  -e GOOGLE_PROJECT_ID=IL_TUO_PROJECT_ID \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=IL_TUO_DEVELOPER_TOKEN \
  -- /opt/homebrew/bin/pipx run --spec git+https://github.com/googleads/google-ads-mcp.git google-ads-mcp

Lo scope user rende il server disponibile in tutti i progetti, non solo in una cartella.

Ricarica la sessione per vedere il server

I server MCP vengono caricati all’avvio della sessione. Dopo aver aggiunto il server, apri una nuova sessione di Claude Code (o ricarica la finestra): solo allora i suoi strumenti diventano disponibili. Con il comando /mcp verifichi che google-ads-mcp compaia tra i server connessi.

Cosa permette di fare (e cosa no)

Una volta connesso, l’MCP risponde a richieste analitiche formulate in linguaggio naturale: per esempio confrontare il costo per conversione delle campagne attive di un account e isolare quelle che si discostano dalla media, oppure ricostruire l’andamento di impression, CTR e conversioni per canale nell’ultimo periodo. La query GAQL viene generata ed eseguita dal server, e la risposta arriva già ordinata e leggibile.

Il perimetro resta quello della sola lettura: si interrogano account, metadati e metriche, ma non si creano né si modificano campagne, budget o annunci. Per l’analisi e la reportistica è sufficiente; la gestione operativa rimane separata.

Collegare Google Ads a Claude tramite l’MCP ufficiale non è un’operazione complessa: il codice da eseguire è minimo.

A fare la differenza sono le attività propedeutiche (l’account amministratore per il developer token, il progetto Google Cloud, il client OAuth proprio e la pubblicazione della schermata di consenso) e la conoscenza anticipata dei punti in cui il setup può inceppare. Una volta impostato, offre un accesso rapido e conversazionale ai dati di tutti i clienti da un’unica configurazione.