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, den Abruf von Ressourcen und die Datenanalyse schreiben. Der Server stellt bestimmte Tools zur Verfügung, die ein LLM selbstständig erkennen und aufrufen kann.

Wichtige Spezifikationen

  • Protokoll:MCP (Model Context Protocol)
  • Modus:Schreibgeschützt (aktuelle Version)
  • Sprache:Python
  • Transport:Standardeingabe/-ausgabe (stdio) oder streamfähiges HTTP (streamable-http / Cloud Run)
  • Authentifizierung:OAuth 2.0 oder Dienstkonto

Funktionsweise der Interaktionsschleife

  1. Anfrage: Ein Nutzer sendet eine Anfrage wie „Wie ist die Kampagnenleistung in dieser Woche?“.
  2. Erkennung:Das LLM prüft die verfügbaren Tools und erkennt die Suchfunktionen von google-ads-mcp.
  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

Führen Sie die folgenden Schritte aus, um den Google Ads MCP-Server zu konfigurieren und zu verwenden.

Vorbereitung

Vor der Konfiguration benötigen Sie die folgenden Anmeldedaten aus der Google Cloud Console:

  • Projekt-ID: Ihre Google Cloud-Projekt-ID (GOOGLE_PROJECT_ID). Prüfen Sie auf der Übersichtsseite der Google Ads API, ob Ihr Projekt die Zugriffsebenen „Explorer“, „Basic“ oder „Standard“ hat. Wenn nicht, beantragen Sie eine dieser Zugriffsebenen. Beachten Sie, dass Entwicklertokens (GOOGLE_ADS_DEVELOPER_TOKEN) am 9. September 2026 eingestellt wurden und in der neuesten Version des Google Ads MCP-Servers nicht mehr erforderlich sind, da die API-Zugriffsebenen mit dem Google Cloud-Projekt verknüpft sind.
  • OAuth-Anmeldedaten: Entweder ein OAuth 2.0-Client-ID/Clientschlüssel-Paar oder eine Reihe von Standardanmeldedaten für Anwendungen.

Konfiguration

Wenn Sie den Server in einen MCP-kompatiblen Host einbinden möchten, fügen Sie den folgenden Eintrag in die MCP-Konfigurationsdatei des Hosts ein, z. B. settings.json, und verweisen Sie GOOGLE_APPLICATION_CREDENTIALS auf Ihre ADC-JSON-Datei. Alternativ können Sie die Standard-ADC mit gcloud auth application-default login konfigurieren. Wenn Sie über ein Verwaltungskonto auf Konten zugreifen, können Sie auch GOOGLE_ADS_LOGIN_CUSTOMER_ID festlegen. Die genaue Position und der Dateiname dieser Konfiguration sind in der Dokumentation Ihres Hosts angegeben.

{
  "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. Erstellen Sie ein Repository in der Artifact Registry:

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

  2. Wechseln Sie zum Projektverzeichnis :

    cd <full path>/google-ads-mcp

  3. Erstellen und übertragen Sie das Image:

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

    Dieser Schritt muss immer ausgeführt werden, wenn Sie den bereitgestellten Server auf die aktuelle 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 2.0-Client-ID (in Ihrem Google Cloud-Projekt als Webanwendung konfiguriert) für die OAuth-Authentifizierung auf Anwendungsebene. Achten Sie darauf, dass:
    • Sie die entsprechenden autorisierten Weiterleitungs-URIs für alle KI-Clients hinzugefügt haben, die Sie verbinden möchten, z. B. https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect oder https://antigravity.google/oauth-callback.
    • Sie den Bereich https://www.googleapis.com/auth/adwords auf dem OAuth-Zustimmungsbildschirm unter APIs & Dienste > OAuth-Zustimmungsbildschirm > Datenzugriff (Bereiche hinzufügen oder entfernen) hinzugefügt haben.
    • Wenn der Veröffentlichungsstatus Ihres OAuth-Zustimmungsbildschirms auf Testen (Standard) festgelegt ist, haben Sie die Google-Konten, die eine Verbindung zum MCP Server herstellen, unter APIs & Dienste > OAuth-Zustimmung Bildschirm > Zielgruppe als Testnutzer hinzugefügt (Testnutzer > + Nutzer hinzufügen).
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Der OAuth-Clientschlüssel, der der OAuth-Client-ID entspricht.
  • GOOGLE_ADS_MCP_BASE_URL: Die öffentliche Basis-URL, über die Ihr MCP-Server zugänglich ist, z. B. https://google-ads-mcp-xyz-uc.a.run.app. Da Google Cloud Run diese URL bei der ersten Bereitstellung generiert, stellen Sie sie zuerst ohne diese Variable bereit und aktualisieren Sie den Dienst nach der Bereitstellung.
  • FASTMCP_HOST: Legen Sie diesen Wert auf 0.0.0.0 fest, damit FastMCP Verbindungen von allen IP-Adressen akzeptieren kann.

Stellen Sie den Dienst in Google Cloud Run bereit:

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"

Nachdem Cloud Run die Bereitstellung abgeschlossen hat, rufen Sie die zugewiesene Dienst-URL ab und aktualisieren Sie den Dienst mit der Umgebungsvariablen 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"

Authentifizierungs- und Sicherheitsmodell

Wenn Sie mit --allow-unauthenticated bereitstellen, wird die IAM-Prüfung auf Infrastrukturebene von Cloud Run (roles/run.invoker) deaktiviert, sodass externe KI-Clients eine Verbindung herstellen können, ohne Google Cloud-Dienstkonto-Tokens zu benötigen. Die Authentifizierung wird stattdessen an die Anwendungsebene delegiert:

  • Wenn GOOGLE_ADS_MCP_OAUTH_CLIENT_ID und GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET angegeben sind, erzwingt der MCP-Server Google OAuth 2.0 für alle eingehenden Anfragen und fordert nicht authentifizierte Aufrufer mit einer HTTP 401-Antwort auf. Alle Toolanfragen werden ausschließlich unter der OAuth-Identität des authentifizierten Aufrufers ausgeführt.
  • Wenn Sie --allow-unauthenticated weglassen, wird IAM für die Cloud Run-Infrastruktur erzwungen. Aufrufer müssen dann mit jeder Anfrage Google Cloud OIDC-Identitätstokens übergeben. Da sich Standard-KI-Clients (z. B. Claude und ChatGPT) mit OAuth für Endnutzer und nicht mit Google Cloud IAM-Identitätstokens authentifizieren, erfordern direkte Verbindungen von diesen Plattformen --allow-unauthenticated mit OAuth auf Anwendungsebene.

MCP-Client konfigurieren

Konfigurieren Sie nach der Bereitstellung Ihren MCP-Client mit der Cloud Run-URL. Da der Server eine OAuth 2.0-Authentifizierung erfordert, muss der Client den MCP-OAuth-Ablauf unterstützen oder ein autorisiertes Inhabertoken bereitstellen:

  • OAuth-fähige Clients:Bei Clients, die die MCP-OAuth-Erkennung unterstützen (z. B. Antigravity), wird beim Herstellen einer Verbindung zum Endpunkt eine Authentifizierungsaufforderung angezeigt, um sich über Google anzumelden und den Zugriffsbereich https://www.googleapis.com/auth/adwords zu gewähren (in der Google Cloud Console als .../auth/adwords aufgeführt).
  • KI-Plattformen von Drittanbietern (Claude, ChatGPT): Fügen Sie in den Connector oder Integrationseinstellungen Ihres Clients einen benutzerdefinierten Connector hinzu, der auf Ihre Cloud Run URL mit dem /mcp Pfad verweist (z. B. https://your-cloud-run-url.a.run.app/mcp). Wählen Sie die OAuth 2.0-Authentifizierung aus (mit Ihrer eigenen OAuth-Client-ID und Ihrem eigenen OAuth-Clientschlüssel) und prüfen Sie, ob der Callback-URI des Clients zu den autorisierten Weiterleitungs-URIs Ihres OAuth-Clients hinzugefügt wurde. Teilnehmer der Pilotphase für gehostete Endpunkte, die auf der Zulassungsliste stehen, können auch die Einrichtungsanleitung für gehostete MCP-Endpunkte verwenden.
  • Clients ohne OAuth-Unterstützung:Clients, die keine HTTP-OAuth-Abläufe unterstützen, erhalten eine HTTP 401-Antwort „Nicht autorisiert“. Verwenden Sie für diese Tools stattdessen die lokale „stdio“-Konfiguration.

Beispielkonfiguration für einen OAuth-fähigen Client (z. B. ~/.gemini/settings.json):

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

Wichtige Funktionen (Tools)

Der Server stellt Tools für die Kontoerkennung und Leistungsberichte zur Verfügung:

  • list_accessible_customers: Gibt die Liste der Google Ads-Kundennummern und Kontonamen zurück, auf die der authentifizierte Nutzer zugreifen kann.
  • search: Führt GAQL-Anfragen (Google Ads Query Language) 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 zu verstehen und zu erfahren, welche Felder für Abfragen verfügbar sind.

Beispiel-Prompts für den Einstieg

Fragen, was der Server kann:

What can the google-ads-mcp server do?

Fragen zu Kunden:

What customers do I have access to?

Fragen zu Kampagnen:

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