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 bridge 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

Panoramica tecnica

Implementando questo server MCP, elimini la necessità di scrivere codice "glue" 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ò scoprire e richiamare autonomamente.

Specifiche principali

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

Come funziona il loop di interazione

  1. Richiesta: un utente invia una query, ad esempio "Qual è il rendimento della mia campagna questa settimana?".
  2. Scoperta: l'LLM ispeziona gli strumenti disponibili e identifica le funzionalità di ricerca di 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 disporre delle seguenti credenziali della console Google Cloud:

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 indirizza GOOGLE_APPLICATION_CREDENTIALS al 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 conoscere la posizione esatta e il nome file 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"
      }
    }
  }
}

(Facoltativo) Fornisci all'agente competenze e l'assistente per sviluppatori

Il server MCP di Google Ads fornisce al tuo client AI l'accesso di sola lettura ai dati dell'account in tempo reale. Per aiutare l'agente a creare query Google Ads Query Language (GAQL) valide, diagnosticare le variazioni del rendimento dell'account e generare il codice della libreria client, associa il server MCP a questi strumenti complementari:

  • Skill dell'agente API Google Ads:moduli portatili di istruzioni e workflow specifici dell'API Google Ads, tra cui google-ads-api-mcp-setup, google-ads-api-account-diagnostics e google-ads-api-quickstart, che insegnano all'agente come utilizzare in modo efficace il server MCP di Google Ads con un overhead di token inferiore. Installale con un solo comando (richiede Node.js) o consulta la guida alle competenze degli agenti dell'API Google Ads per le opzioni Antigravity, Claude Code, Codex e Cursor:

    npx skills add google/skills/skills/ads

  • Assistente per sviluppatori API Google Ads: un plug-in modulare per Google Antigravity e Claude Code che fornisce l'ispezione locale dello schema Protobuf, la convalida GAQL programmatica, la generazione di codice della libreria client (inclusi gli script di mutazione) e la risoluzione dei problemi delle conversioni offline. Scopri come funziona in Che cos'è l'Assistente per gli sviluppatori dell'API Google Ads? o segui la guida all'installazione.

Deployment su Google Cloud

Anziché ospitare questo server MCP localmente, puoi ospitarlo su Google Cloud Run o su qualsiasi altra infrastruttura basata su 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 un'immagine Docker ed eseguine il push

Puoi utilizzare Cloud Build per creare l'immagine ed eseguirne il push ad Artifact Registry senza dover installare Docker localmente.

  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 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 che:
    • Hai aggiunto gli URI di reindirizzamento autorizzati appropriati per tutti i client AI che prevedi di 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), hai aggiunto gli Account Google che si connettono al server MCP come Utenti di test in API e servizi > Schermata per il consenso OAuth > Pubblico (Utenti di test > + 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 tuo 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"

Dopo che Cloud Run ha completato il deployment, 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 disabilita 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 degli account di servizio 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, contestando i chiamanti non autenticati con una risposta HTTP 401. Tutte le richieste degli strumenti vengono eseguite rigorosamente con l'identità OAuth del chiamante autenticato.
  • Se ometti --allow-unauthenticated, viene applicato l'IAM dell'infrastruttura Cloud Run, che richiede ai chiamanti di passare i token di identità 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 di identità Google Cloud IAM, 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 punti 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 tuo client secret) e assicurati che l'URI di callback del client sia aggiunto agli URI di reindirizzamento autorizzati del client OAuth. (I partecipanti al progetto pilota degli endpoint in hosting inclusi nella lista consentita possono anche consultare la guida alla configurazione di MCP in hosting.)
  • Client senza supporto OAuth:i client che non supportano i flussi OAuth HTTP riceveranno una risposta HTTP 401 Non autorizzato. Per questi strumenti, utilizza invece la configurazione stdio locale.

Esempio di configurazione per un client compatibile con 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 richieste GAQL per recuperare le metriche, i budget e lo stato delle risorse.

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

    Questo è utile per comprendere la struttura dei dati e quali campi sono disponibili per le query.

Prompt di esempio 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

Passaggi successivi