Google Ads MCP e Claude Desktop: come migrare dopo il ritiro del developer token

Introduzione

Dal 9 settembre 2026 il server MCP ufficiale di Google Ads non ha più bisogno del developer token: l’accesso all’API è legato al progetto Google Cloud. Chi usa Claude Desktop per interrogare i propri account Google Ads deve quindi rivedere la configurazione, anche se in molti casi tutto continua a funzionare. Google lo ha annunciato il 10 settembre sul Google Ads Developer Blog e il ritiro compare nella tabella dei ritiri dell’API.

Il server MCP di Google Ads è lo strumento ufficiale che collega un assistente AI come Claude all’API Google Ads. È scritto in Python, funziona in sola lettura ed espone tre strumenti: list_accessible_customers, search (query GAQL) e get_resource_metadata. In pratica permette di chiedere in linguaggio naturale “com’è andata la campagna X la settimana scorsa?” e ottenere i dati reali dell’account.

La vecchia impostazione

Fino a settembre 2026 servivano tre ingredienti: un developer token, un progetto Google Cloud e le credenziali OAuth dell’utente. Il token si richiedeva dal Centro API dell’account amministratore (MCC) e il suo livello di accesso (Test, Basic, Standard) decideva su quali account si potevano fare chiamate.

La procedura tipica era:

1. Richiedere il developer token in Google Ads, Amministrazione › Centro API dell’MCC.
2. Creare un progetto Google Cloud, abilitare la Google Ads API e un client OAuth.
3. Generare le credenziali con gcloud auth application-default login, che salva un file ADC nella cartella di gcloud.
4. Installare il server con pip e avviarlo come modulo Python.

La voce nel claude_desktop_config.json di Claude Desktop era simile a questa:

"google-ads": {
  "command": "python",
  "args": ["-m", "ads_mcp"],
  "env": {
    "GOOGLE_APPLICATION_CREDENTIALS": "C:\\Users\\UTENTE\\AppData\\Roaming\\gcloud\\application_default_credentials.json",
    "GOOGLE_PROJECT_ID": "ID_PROGETTO",
    "GOOGLE_ADS_DEVELOPER_TOKEN": "IL_TUO_TOKEN",
    "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "ID_MCC"
  }
}

Chi gestisce più MCC può duplicare la voce con un nome diverso (ad esempio google-ads e google-ads-cliente2), cambiando solo GOOGLE_ADS_LOGIN_CUSTOMER_ID. È uno schema che resta valido anche con la nuova impostazione.

La nuova impostazione

Oggi bastano un progetto Google Cloud con un livello di accesso adeguato e un file di credenziali OAuth: il developer token è sparito dalla procedura. Secondo la pagina ufficiale sul token sviluppatore, i livelli di accesso ora appartengono al progetto Cloud e si gestiscono dalla pagina Panoramica della Google Ads API nella Cloud Console. Il Centro API dell’MCC resta consultabile solo come archivio, e il suo modulo serve ormai solo per l’API di monitoraggio delle conversioni da app.

Il concetto chiave da tenere a mente: il livello di accesso dipende dal progetto Cloud che possiede il client OAuth con cui hai generato le credenziali. Inoltre non serve più un account amministratore per usare l’API: l’MCC resta utile solo per gestire più account dalla stessa utenza.

1. Progetto Google Cloud e livello di accesso

1. In Google Cloud Console crea un progetto e abilita la Google Ads API. Il progetto parte con l’accesso Test, valido solo per gli account di test.
2. Apri la pagina Panoramica della Google Ads API, espandi la sezione per l’upgrade del livello di accesso e richiedi Explorer: spesso viene approvato in automatico.
3. Controlla la fatturazione: un progetto legato a un account di prova gratuita si vede rifiutare le richieste Explorer e Basic (problema noto documentato da Google). Le soluzioni indicate sono passare a un account a pagamento oppure scollegare la fatturazione, se il progetto serve solo per Google Ads.
4. Per gestire i livelli di accesso servono i ruoli IAM di Proprietario, Editor, Amministratore quota o Amministratore Service Usage sul progetto.

Per un uso in sola lettura come quello del server MCP, Explorer di solito basta: le sue limitazioni riguardano funzioni come la pianificazione delle parole chiave, la creazione di account e la fatturazione (dettagli nella pagina sui livelli di accesso). Per Basic serve invece la verifica del brand sulla schermata di consenso OAuth, quindi un URL di homepage e uno di privacy policy.

2. Client OAuth e schermata di consenso

1. In Google Auth Platform configura la schermata di consenso: tipo utente Esterno, aggiungi il tuo indirizzo tra gli utenti di test.
2. Crea un client OAuth di tipo App desktop e scarica il JSON, ad esempio come C:\mcp-servers\google-ads-mcp\client_secret.json.

Attenzione allo stato di pubblicazione: con l’app in modalità Test il refresh token scade dopo 7 giorni (documentazione OAuth 2.0). Per evitarlo bisogna pubblicare l’app dalla pagina Audience. Un’app pubblicata ma non verificata mostra l’avviso “app non verificata” e ha un tetto di 100 utenti: per un uso personale non è un problema.

3. Refresh token senza gcloud

Il server legge le credenziali tramite Application Default Credentials, quindi accetta un file authorized_user indicato da GOOGLE_APPLICATION_CREDENTIALS. È lo stesso formato del file creato da gcloud auth application-default login, la strada indicata nel README. Se non vuoi installare gcloud, puoi generarlo con un piccolo script Python:

import json
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ["https://www.googleapis.com/auth/adwords",
          "https://www.googleapis.com/auth/cloud-platform"]
flow = InstalledAppFlow.from_client_secrets_file(
    r"C:\mcp-servers\google-ads-mcp\client_secret.json", SCOPES)
creds = flow.run_local_server(port=0, prompt="consent", access_type="offline")

data = {"type": "authorized_user",
        "client_id": creds.client_id,
        "client_secret": creds.client_secret,
        "refresh_token": creds.refresh_token}
with open(r"C:\mcp-servers\google-ads-mcp\credentials.json", "w") as f:
    json.dump(data, f, indent=2)
print("Fatto.")

Prima installa la libreria con py -m pip install --user google-auth-oauthlib, poi salva lo script in un file .py e lancialo con py genera_token.py. Si apre il browser: accedi con l’account amministratore dell’MCC e autorizza. Alla schermata “app non verificata” scegli Avanzate › Vai a….

4. Installazione del server

Il README su GitHub propone pipx run, che scarica il server a ogni avvio. Su Windows mi è stato più affidabile installarlo una volta sola:

python -m pip install --user pipx
python -m pipx install git+https://github.com/googleads/google-ads-mcp.git

L’eseguibile finisce di solito in C:\Users\UTENTE\.local\bin\google-ads-mcp.exe. Per aggiornarlo: python -m pipx upgrade google-ads-mcp.

5. Configurazione di Claude Desktop

"google-ads-mcp": {
  "command": "C:\\Users\\UTENTE\\.local\\bin\\google-ads-mcp.exe",
  "args": [],
  "env": {
    "GOOGLE_PROJECT_ID": "ID_PROGETTO",
    "GOOGLE_CLOUD_PROJECT": "ID_PROGETTO",
    "GOOGLE_APPLICATION_CREDENTIALS": "C:\\mcp-servers\\google-ads-mcp\\credentials.json",
    "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "ID_MCC_SENZA_TRATTINI"
  }
}

GOOGLE_ADS_LOGIN_CUSTOMER_ID va impostato sull’MCC di livello più alto: così il server può interrogare tutti gli account della gerarchia. GOOGLE_CLOUD_PROJECT non è indispensabile, ma lo consiglia anche il README ed evita un avviso della libreria di autenticazione. Nel JSON i backslash vanno raddoppiati.

Nota: mentre scrivo, gli esempi del README includono ancora GOOGLE_ADS_DEVELOPER_TOKEN, ma la guida ufficiale di Google conferma che con la versione attuale del server non serve più. Puoi ometterlo.

Una nota sulle fonti: la guida di Anthropic sui server MCP locali oggi raccomanda le Desktop Extensions; la sintassi mcpServers qui sopra è quella degli esempi della guida Google e del README. La stessa guida spiega come verificare la connessione: pulsante + nella chat › Connettori, oppure le impostazioni Sviluppatore per stato e log.

Aggiornare una configurazione esistente

Chi aveva già tutto funzionante non perde l’accesso il 9 settembre: Google ha trasferito il livello del vecchio token ai progetti Cloud usati con quel token negli ultimi 90 giorni, e il token ancora presente nella configurazione viene semplicemente ignorato. Conviene però fare pulizia in cinque passaggi.

1. Verifica il livello di accesso nella pagina Panoramica della Google Ads API del progetto usato e confrontalo con quello del vecchio token, ancora visibile nel Centro API. Se non corrispondono, richiedi di nuovo l’accesso dalla Panoramica.
2. Aggiorna il server, con Claude Desktop chiuso: python -m pip install --upgrade git+https://github.com/googleads/google-ads-mcp.git.
3. Cambia il comando di avvio. Con la versione più recente del pacchetto (nel mio caso la 0.0.5, installata dal repository) python -m ads_mcp non funziona più: va usato l’eseguibile google-ads-mcp.exe. Il percorso esatto si trova con where.exe google-ads-mcp.
4. Togli GOOGLE_ADS_DEVELOPER_TOKEN dalle voci della configurazione. Google ha annunciato che i token verranno rifiutati in una futura versione principale dell’API.
5. Controlla i contatti IAM. Le comunicazioni obbligatorie di Google arriveranno ai Proprietari ed Editor del progetto Cloud: verifica nella pagina IAM che l’elenco sia aggiornato.

Un consiglio in più: se le credenziali puntano al file ADC predefinito di gcloud, copialo in una cartella dedicata e aggiorna GOOGLE_APPLICATION_CREDENTIALS. Altrimenti il prossimo gcloud auth application-default login, fatto per qualsiasi altro motivo, lo sovrascrive e il server smette di funzionare.

Troubleshooting

Quasi tutti i problemi si diagnosticano dal log del server: in Claude Desktop vai in Impostazioni › Sviluppatore, seleziona il server e apri Visualizza log. Questi sono gli errori che ho incontrato davvero, più due problemi noti documentati da Google. Per un approfondimento generale c’è la guida al debug di MCP.

Gli errori di permesso sugli account. Per esplorare, Claude spesso parte da list_accessible_customers, che restituisce anche account fuori dall’MCC configurato, e poi li interroga tutti. Quelli fuori gerarchia rispondono con errore. Basta indirizzarlo: “Elenca gli account sotto l’MCC [ID] interrogando customer_client, poi analizza l’account [ID]”. Se lavori spesso così, conviene metterlo nelle istruzioni del progetto.

I nomi dei tool e il file tools_config.yaml. Nel log puoi trovare la riga No local 'tools_config.yaml' found e nomi di tool come search_search: è normale. Le versioni recenti raggruppano i tool in namespace configurabili con un file tools_config.yaml (descritto nel README); senza file il server usa la configurazione predefinita, con tutti i tool attivi.

Gli errori più banali, che però costano tempo:

• Il config non cambia. Se Claude Desktop è aperto, anche solo nella tray, può sovrascrivere il file al riavvio. Chiudilo con tasto destro › Esci prima di salvare.
• Codice Python incollato in PowerShell. Lo script del token va salvato in un file .py, non incollato nel terminale.
• Estensioni nascoste di Windows. Un file che sembra client_secret.json può essere in realtà client_secret.json.json.
• JSON non valido. Controlla le virgole tra le voci e i backslash doppi nei percorsi.

Conclusioni

La migrazione semplifica le cose: niente più token da richiedere e custodire, e l’accesso si governa interamente dal progetto Google Cloud. Il prezzo da pagare è qualche passaggio nuovo da conoscere, cioè il livello di accesso del progetto, lo stato dell’app OAuth e il nuovo comando di avvio del server. Una volta sistemati, il server risponde in pochi secondi e Claude diventa un ottimo assistente per analisi e report sugli account Google Ads.

Se gestisci più centri clienti, tieni una voce di configurazione per ogni MCC e, nei prompt, indica sempre su quale lavorare.

Fonti ufficiali

• A new onboarding experience for Google Ads API developers – Google Ads Developer Blog, 10 settembre 2026 (annuncio del ritiro dei developer token)
• Ritiri di funzionalità e modifiche senza controllo delle versioni – Google for Developers (voce del 9 settembre 2026)
• Token sviluppatore – Google for Developers (FAQ e problemi noti)
• Livelli di accesso e utilizzo consentito – Google for Developers
• Accelerate Google Ads API Basic Access reviews with brand verification – Google Ads Developer Blog, 7 luglio 2026 (contesto sulla verifica del brand)
• Server MCP di Google Ads: guida all’integrazione per gli sviluppatori – Google for Developers
• googleads/google-ads-mcp – GitHub
• Come funzionano le credenziali predefinite dell’applicazione – Google Cloud
• Utilizzare OAuth 2.0 per accedere alle API di Google – Google Identity
• Manage App Audience – Google Cloud Help
• Getting Started with Local MCP Servers on Claude Desktop – Anthropic

Stefano Salustri

Sono un Consulente in Digital Marketing con oltre 10 anni di esperienza. Mi occupo di progettare e sviluppare strategie digitali per Piccole e Medie Imprese per aiutare le aziende ad ottenere il massimo ritorno dagli investimenti nei canali online.