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

Il Model Context Protocol (MCP) è uno standard aperto che consente ai modelli Large Language Model (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, non dovrai 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)
  • Autenticazione: OAuth 2.0 o account di servizio

Come funziona il ciclo di interazione

  1. Richiesta: un utente invia una query come "Come sta andando 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 console per sviluppatori Google Ads:

  • Token sviluppatore: la stringa di accesso univoca composta da 22 caratteri.
  • ID progetto: l'identificatore del progetto Google Cloud.
  • Credenziali OAuth: una coppia ID client OAuth 2.0/secret client o un insieme di credenziali predefinite dell'applicazione.

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. Consulta la documentazione dell'host per la posizione e il nome file esatti di questa configurazione.

JSON

{
  "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_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
      }
    }
  }
}

Deployment su Google Cloud

Anziché ospitare questo server MCP localmente, 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 localmente.

  1. Crea un repository in Artifact Registry:

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

  2. 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.
  • GOOGLE_ADS_DEVELOPER_TOKEN: il token sviluppatore che vuoi che il server MCP utilizzi.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: l'ID client OAuth che vuoi che il server MCP utilizzi.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: il secret client OAuth che vuoi che il server MCP utilizzi.
  • GOOGLE_ADS_MCP_BASE_URL: l'URL di base in cui è accessibile il server MCP. Questo valore verrà assegnato automaticamente da Google Cloud Run dopo il primo deployment. Puoi aggiornare le variabili di ambiente 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.
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_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0"

Configura il client MCP

Dopo il deployment, aggiorna la configurazione del client MCP (ad esempio, ~/.gemini/settings.json) in modo che utilizzi l'URL di Cloud Run.

{
  "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 di 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 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