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

Panoramica tecnica

Implementando questo server MCP, non è più necessario 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 (versione attuale)
  • Lingua: Python
  • Trasporto:input/output standard (stdio) o HTTP/SSE (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. Scoperta: l'LLM esamina gli strumenti disponibili e identifica le google-ads-mcp funzionalità di ricerca.
  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 da una persona.

Inizia

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

Prerequisiti

Prima della configurazione, assicurati di disporre delle seguenti credenziali dalla 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 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 del tuo 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 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 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. 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 che vuoi che il server MCP utilizzi.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: il client secret OAuth che vuoi che il server MCP utilizzi.
  • GOOGLE_ADS_MCP_BASE_URL: l'URL di base in cui è accessibile il server MCP; questo viene 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_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) per utilizzare l'URL 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 l'individuazione degli account e la generazione di report sul rendimento:

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

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

    Ciò è 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?

Domande sui clienti:

What customers do I have access to?

Domande 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