Google Ads-MCP-Server: Entwickler-Integrationsleitfaden

Das Model Context Protocol (MCP) ist ein offener Standard, der es Large Language Models (LLMs) ermöglicht, sicher mit externen Daten und Anwendungen zu interagieren. Der Google Ads MCP-Server bietet eine standardisierte Brücke zur Google Ads API, mit der KI-Agents Kampagnendaten in natürlicher Sprache analysieren und abrufen können.

Community-Ressourcen und Support

Technische Übersicht

Durch die Implementierung dieses MCP-Servers müssen Sie keinen benutzerdefinierten „Glue-Code“ für die Google Ads API-Authentifizierung, das Abrufen von Ressourcen und das Parsen von Daten schreiben. Der Server stellt bestimmte Tools zur Verfügung, die ein LLM autonom erkennen und aufrufen kann.

Wichtige Spezifikationen

  • Protokoll:MCP (Model Context Protocol)
  • Modus:Nur Lesezugriff (aktuelle Version)
  • Sprache:Python
  • Transport:Standardein-/ausgabe (stdio) oder HTTP/SSE (Cloud Run)
  • Authentifizierung:OAuth 2.0 oder Dienstkonto

So funktioniert der Interaktionszyklus

  1. Anfrage:Ein Nutzer stellt eine Frage wie „Wie ist die Kampagnenleistung in dieser Woche?“.
  2. Erkennung:Das LLM untersucht die verfügbaren Tools und identifiziert die google-ads-mcp-Suchfunktionen.
  3. Ausführung:Der MCP-Server führt die zugrunde liegende Python-Logik aus, um die Google Ads API abzufragen.
  4. Kontexteinfügung:Strukturierte Ergebnisse werden an das Kontextfenster des LLM zurückgegeben.
  5. Antwort:Das LLM fasst die Daten in einer für Menschen lesbaren Antwort zusammen.

Jetzt starten

So konfigurieren und verwenden Sie den Google Ads MCP-Server.

Vorbereitung

Prüfen Sie vor der Konfiguration, ob Sie die folgenden Anmeldedaten aus der Google Cloud Console haben:

Konfiguration

Wenn Sie den Server in einen MCP-kompatiblen Host einbinden möchten, fügen Sie der MCP-Konfigurationsdatei Ihres Hosts, z. B. settings.json, den folgenden Eintrag hinzu und verweisen Sie GOOGLE_APPLICATION_CREDENTIALS auf Ihre ADC-JSON-Datei (oder konfigurieren Sie den Standard-ADC mit gcloud auth application-default login). Wenn Sie über ein Verwaltungskonto auf Konten zugreifen, können Sie auch GOOGLE_ADS_LOGIN_CUSTOMER_ID festlegen. In der Dokumentation Ihres Hosts finden Sie den genauen Speicherort und Dateinamen dieser Konfiguration.

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

Bereitstellung in Google Cloud

Anstatt diesen MCP-Server lokal zu hosten, können Sie ihn in Google Cloud Run oder in einer anderen cloudbasierten Infrastruktur hosten. Das ist nützlich, wenn Sie den Server für verschiedene Agents freigeben oder als Webdienst ausführen möchten.

Vorbereitung

  1. Ein Google Cloud-Projekt.

  2. Das gcloud-Befehlszeilentool ist installiert, authentifiziert und ein aktives Projekt ist konfiguriert:

    gcloud config set project YOUR_PROJECT_ID

Docker-Image erstellen und übertragen

Mit Cloud Build können Sie das Image erstellen und in die Artifact Registry übertragen, ohne Docker lokal installieren zu müssen.

  1. Repository in Artifact Registry erstellen:

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

  2. Zum Projektverzeichnis wechseln:

    cd <full path>/google-ads-mcp

  3. Erstellen Sie das Bild und senden Sie es ein:

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

    Dieser Schritt muss jedes Mal ausgeführt werden, wenn Sie den bereitgestellten Server auf die neueste Version aktualisieren möchten.

In Google Cloud Run bereitstellen

Legen Sie die erforderlichen Umgebungsvariablen fest:

  • GOOGLE_PROJECT_ID: Ihre Google Cloud-Projekt-ID mit den entsprechenden API-Zugriffsebenen.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Die OAuth-Client-ID, die der MCP-Server verwenden soll.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Der OAuth-Clientschlüssel, den der MCP-Server verwenden soll.
  • GOOGLE_ADS_MCP_BASE_URL: Die Basis-URL, über die Ihr MCP-Server erreichbar ist. Sie wird nach der ersten Bereitstellung automatisch von Google Cloud Run zugewiesen. Sie können die Umgebungsvariablen nach der Bereitstellung aktualisieren.
  • FASTMCP_HOST: Setzen Sie diesen Wert auf 0.0.0.0, damit FastMCP Verbindungen von allen IP-Adressen akzeptieren kann.
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"

MCP-Client konfigurieren

Aktualisieren Sie nach der Bereitstellung die Konfiguration Ihres MCP-Clients (z. B. ~/.gemini/settings.json), damit die Cloud Run-URL verwendet wird.

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

Hauptfunktionen (Tools)

Der Server stellt Tools für die Kontoermittlung und Leistungsberichte bereit:

  • list_accessible_customers: Gibt die Liste der Google Ads-Kundennummern und Kontonamen zurück, auf die der authentifizierte Nutzer zugreifen kann.
  • search: Führt Google Ads Query Language-Anfragen (GAQL) aus, um Ressourcenmesswerte, Budgets und Status abzurufen.

  • get_resource_metadata: Ruft Metadaten zu einem Google Ads API-Ressourcentyp ab, z. B. "campaign".

    Das ist nützlich, um die Struktur der Daten und die Felder zu verstehen, die für Abfragen verfügbar sind.

Beispiel-Prompts für den Einstieg

Fragen Sie, was der Server tun kann:

What can the google-ads-mcp server do?

Fragen zu Kunden:

What customers do I have access to?

Fragen zu Kampagnen stellen:

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