Server MCP di Google Ads: guida all'integrazione per gli sviluppatori

Il Model Context Protocol (MCP) è uno standard aperto che consente ai modelli linguistici di grandi dimensioni (LLM) di interagire in modo sicuro con dati e applicazioni esterni. Il server MCP di Google Ads fornisce un ponte standardizzato all'API Google Ads, che consente agli agenti AI di analizzare e recuperare i dati delle campagne utilizzando il linguaggio naturale.

Risorse e assistenza della community

  • Repository GitHub: trova demo, esempi e segnala bug o suggerisci funzionalità nel repository google-ads-mcp.

    Utilizza la scheda Problemi per segnalare bug e richiedere funzionalità.

  • Community: unisciti al canale #ads-api-ai-tools su Discord della community Google Advertising.

Panoramica tecnica

Implementando questo server MCP, non è più necessario scrivere "codice di collegamento" personalizzato per l'autenticazione dell'API Google Ads, il recupero delle risorse e l'analisi dei dati. Il server espone strumenti specifici che un LLM può rilevare e richiamare autonomamente.

Specifiche principali

  • Protocollo: MCP (Model Context Protocol)
  • Modalità: sola lettura (release attuale)
  • Lingua: Python
  • Trasporto: input/output standard (stdio) o HTTP in streaming (streamable-http / Cloud Run)
  • Autenticazione: OAuth 2.0 o service account

Come funziona il ciclo di interazione

  1. Richiesta: un utente invia una query come "Qual è il rendimento della mia campagna questa settimana?".
  2. Rilevamento: l'LLM esamina gli strumenti disponibili e identifica le funzionalità di ricerca google-ads-mcp.
  3. Esecuzione: il server MCP esegue la logica Python sottostante per eseguire query sull'API Google Ads.
  4. Inserimento del contesto: i risultati strutturati vengono restituiti alla finestra di contesto dell'LLM.
  5. Risposta: l'LLM sintetizza i dati in una risposta leggibile.

Inizia

Segui questi passaggi per configurare e utilizzare il server MCP di Google Ads.

Prerequisiti

Prima della configurazione, assicurati di avere le seguenti credenziali dalla Google Cloud console:

Configurazione

Per integrare il server in un host compatibile con MCP, aggiungi la seguente voce al file di configurazione MCP dell'host, ad esempio settings.json, e imposta GOOGLE_APPLICATION_CREDENTIALS sul file JSON ADC (o configura l'ADC predefinito con gcloud auth application-default login). Se accedi agli account tramite un account amministratore, puoi anche impostare GOOGLE_ADS_LOGIN_CUSTOMER_ID. Consulta la documentazione dell'host per la posizione e il nome file esatti di questa configurazione.

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

Deployment su Google Cloud

Anziché ospitare questo server MCP in locale, puoi ospitarlo su Google Cloud Run o su qualsiasi altra infrastruttura basata sul cloud. Questa opzione è utile se vuoi condividere il server tra diversi agenti o eseguirlo come servizio web.

Prerequisiti

  1. Un progetto Google Cloud.

  2. Lo strumento a riga di comando gcloud installato, autenticato e con un progetto attivo configurato:

    gcloud config set project YOUR_PROJECT_ID

Crea ed esegui il push di un'immagine Docker

Puoi utilizzare Cloud Build per creare ed eseguire il push dell'immagine in Artifact Registry senza dover installare Docker in locale.

  1. Crea un repository in Artifact Registry:

    gcloud artifacts repositories create mcp-servers \
  --repository-format=docker --location=us-central1

  2. Vai alla directory del progetto:

    cd <full path>/google-ads-mcp

  3. Crea e invia l'immagine:

    gcloud builds submit \
  --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .

    Tieni presente che questo passaggio deve essere eseguito ogni volta che vuoi aggiornare il server di cui è stato eseguito il deployment all'ultima versione.

Esegui il deployment in Google Cloud Run

Assicurati di impostare le variabili di ambiente richieste:

  • GOOGLE_PROJECT_ID: l'ID del tuo progetto Google Cloud, che dispone dei livelli di accesso all'API appropriati.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: l'ID client OAuth 2.0 (configurato come applicazione web nel tuo progetto Google Cloud) per l'autenticazione OAuth a livello di applicazione. Assicurati di:
    • Aver aggiunto gli URI di reindirizzamento autorizzati appropriati per tutti i client AI che intendi connettere (ad esempio https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect o https://antigravity.google/oauth-callback).
    • Hai aggiunto l'ambito https://www.googleapis.com/auth/adwords alla schermata per il consenso OAuth in API e servizi > Schermata per il consenso OAuth > Accesso ai dati (Aggiungi o rimuovi ambiti).
    • Se lo stato di pubblicazione della schermata per il consenso OAuth è impostato su Test (impostazione predefinita), aver aggiunto gli Account Google che si connettono al server MCP come Utenti di prova in API e servizi > Schermata per il consenso OAuth > Pubblico (Utenti di prova > + Aggiungi utenti).
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: il client secret OAuth corrispondente all'ID client OAuth.
  • GOOGLE_ADS_MCP_BASE_URL: l'URL di base pubblico in cui è accessibile il server MCP (ad esempio https://google-ads-mcp-xyz-uc.a.run.app). Poiché Google Cloud Run genera questo URL durante il deployment iniziale, esegui il deployment senza questa variabile, quindi aggiorna il servizio dopo il deployment.
  • FASTMCP_HOST: imposta questo valore su 0.0.0.0 per consentire a FastMCP di accettare connessioni da tutti gli indirizzi IP.

Esegui il deployment del servizio in Google Cloud Run:

gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,FASTMCP_HOST=0.0.0.0"

Una volta completato il deployment da parte di Cloud Run, recupera l'URL del servizio assegnato e aggiorna il servizio con la variabile di ambiente GOOGLE_ADS_MCP_BASE_URL:

gcloud run services update google-ads-mcp \
  --region us-central1 \
  --update-env-vars="GOOGLE_ADS_MCP_BASE_URL=https://your-cloud-run-url.a.run.app"

Modello di autenticazione e sicurezza

Il deployment con --allow-unauthenticated disattiva il controllo IAM a livello di infrastruttura di Cloud Run (roles/run.invoker), in modo che i client AI esterni possano connettersi senza bisogno di token del service account Google Cloud. L'autenticazione viene invece delegata al livello di applicazione:

  • Quando vengono forniti GOOGLE_ADS_MCP_OAUTH_CLIENT_ID e GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET, il server MCP applica Google OAuth 2.0 a tutte le richieste in entrata, sfidando i chiamanti non autenticati con una risposta HTTP 401. Tutte le richieste di strumenti vengono eseguite rigorosamente con l'identità OAuth del chiamante autenticato.
  • Se ometti --allow-unauthenticated, viene applicato l'IAM dell'infrastruttura di Cloud Run, che richiede ai chiamanti di trasmettere i token ID OIDC di Google Cloud con ogni richiesta. Poiché i client AI standard (come Claude e ChatGPT) eseguono l'autenticazione utilizzando OAuth dell'utente finale anziché i token ID Cloud IAM di Google Cloud, le connessioni dirette da queste piattaforme richiedono --allow-unauthenticated con OAuth a livello di applicazione.

Configura il client MCP

Dopo il deployment, configura il client MCP con l'URL di Cloud Run. Poiché il server richiede l'autenticazione OAuth 2.0, il client deve supportare il flusso OAuth MCP o fornire un token di connessione autorizzato:

  • Client abilitati per OAuth: per i client che supportano il rilevamento OAuth MCP (come Antigravity), la connessione all'endpoint attiva un prompt di autenticazione per accedere con Google e concedere l'ambito https://www.googleapis.com/auth/adwords (elencato come .../auth/adwords nella console Google Cloud).
  • Piattaforme AI di terze parti (Claude, ChatGPT): nelle impostazioni del connettore o dell'integrazione del client, aggiungi un connettore personalizzato che rimandi all'URL di Cloud Run con il percorso /mcp (ad esempio, https://your-cloud-run-url.a.run.app/mcp), seleziona l'autenticazione OAuth 2.0 (utilizzando il tuo ID client OAuth e il client secret) e assicurati che l'URI di callback del client sia aggiunto agli URI di reindirizzamento autorizzati del client OAuth. (I partecipanti inclusi nella lista consentita del progetto pilota dell'endpoint ospitato possono anche consultare la guida alla configurazione di MCP ospitato.)
  • Client senza supporto OAuth: i client che non supportano i flussi HTTP OAuth riceveranno una risposta HTTP 401 Unauthorized. Per questi strumenti, utilizza invece la configurazione stdio locale.

Esempio di configurazione per un client con funzionalità OAuth (ad esempio, ~/.gemini/settings.json):

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

Funzionalità principali (strumenti)

Il server espone strumenti progettati per il rilevamento degli account e la generazione di report sul rendimento:

  • list_accessible_customers: restituisce l'elenco degli ID cliente Google Ads e dei nomi degli account accessibili all'utente autenticato.
  • search: esegue le richieste Google Ads Query Language (GAQL) per recuperare le metriche, i budget e lo stato delle risorse.

  • get_resource_metadata: recupera i metadati di un tipo di risorsa dell'API Google Ads, ad esempio "campaign".

    Questa opzione è utile per comprendere la struttura dei dati e i campi disponibili per le query.

Esempi di prompt per iniziare

Chiedi cosa può fare il server:

What can the google-ads-mcp server do?

Chiedi informazioni sui clienti:

What customers do I have access to?

Chiedi informazioni sulle campagne:

How many active campaigns do I have?
How is my campaign performance this week?
Give me a report of the top spending campaigns split by device category over the
last 7 days for account 1234567890