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, über die KI-Agenten 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 Authentifizierung, das Abrufen von Ressourcen und das Parsen von Daten in der Google Ads API schreiben. Der Server stellt bestimmte Tools bereit, die ein LLM selbstständig finden und aufrufen kann.

Wichtige Spezifikationen

  • Protokoll: MCP (Model Context Protocol)
  • Modus: Schreibgeschützt (aktueller Release)
  • 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 identifiziert 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. Kontext-Injection: Strukturierte Ergebnisse werden an das Kontextfenster des LLM zurückgegeben.
  5. Antwort: Das LLM fasst die Daten in einer menschenlesbaren Antwort zusammen.

Jetzt starten

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

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 Zugriffsebene „Explorer“, „Basic“ oder „Standardzugriff“ hat. Falls nicht, beantragen Sie eine dieser Zugriffsebenen. Entwicklertokens (GOOGLE_ADS_DEVELOPER_TOKEN) wurden am 9. September 2026 eingestellt und sind in der neuesten Version des Google Ads-MCP-Servers nicht mehr erforderlich, da API-Zugriffsebenen mit dem Google Cloud-Projekt verknüpft sind.
  • OAuth-Anmeldedaten: Entweder ein Paar aus OAuth 2.0-Client-ID und Clientschlüssel oder ein Satz von Standardanmeldedaten für Anwendungen.

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 mit GOOGLE_APPLICATION_CREDENTIALS auf Ihre ADC-JSON-Datei (oder konfigurieren Sie die 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"
      }
    }
  }
}

Optional: KI-Agenten mit Skills und dem Developer Assistant ausstatten

Der Google Ads-MCP-Server bietet Ihrem KI-Client Lesezugriff auf Live-Kontodaten. Damit Ihr Agent gültige Google Ads Query Language (GAQL)-Abfragen erstellen, Leistungsänderungen im Konto diagnostizieren und Clientbibliothekscode generieren kann, sollten Sie den MCP-Server mit den folgenden Begleittools kombinieren:

  • Google Ads API-Agenten-Skills: Übertragbare Module mit Google Ads API-spezifischen Anweisungen und Workflows, einschließlich google-ads-api-mcp-setup, google-ads-api-account-diagnostics und google-ads-api-quickstart, die Ihrem Agenten beibringen, wie er den Google Ads-MCP-Server effektiv und mit geringerem Token-Overhead nutzt. Sie können sie mit einem einzigen Befehl installieren (erfordert Node.js) oder sich die Anleitung zu den Agent-Skills für die Google Ads API für Antigravity, Claude Code, Codex und Cursor ansehen:

    npx skills add google/skills/skills/ads

  • Google Ads API Developer Assistant: Ein modulares Plug-in für Google Antigravity und Claude Code, das eine lokale Protobuf-Schemaprüfung, eine programmatische GAQL-Validierung, die Generierung von Clientbibliotheks-Code (einschließlich Mutate-Skripts) und die Fehlerbehebung bei Offline-Conversions ermöglicht. Weitere Informationen finden Sie unter Was ist der Google Ads API Developer Assistant? oder in der Installationsanleitung.

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 Agenten freigeben oder als Webdienst ausführen möchten.

Vorbereitung

  1. Ein Google Cloud-Projekt.

  2. Das gcloud-Befehlszeilentool ist installiert, authentifiziert und mit einem aktiven Projekt konfiguriert:

    gcloud config set project YOUR_PROJECT_ID

Docker-Image erstellen und per Push übertragen

Mit Cloud Build können Sie das Image erstellen und in 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. Wechseln Sie zum Projektverzeichnis:

    cd <full path>/google-ads-mcp

  3. Erstellen Sie das Image und reichen Sie es ein:

    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 auf Folgendes:
    • Sie haben die entsprechenden autorisierten Weiterleitungs-URIs für alle KI-Clients hinzugefügt, 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 haben den Bereich https://www.googleapis.com/auth/adwords auf dem OAuth-Zustimmungsbildschirm unter APIs und Dienste > OAuth-Zustimmungsbildschirm > Datenzugriff (Bereiche hinzufügen oder entfernen) hinzugefügt.
    • Wenn der Veröffentlichungsstatus Ihres OAuth-Zustimmungsbildschirms auf Test (Standard) festgelegt ist, haben Sie die Google-Konten, die eine Verbindung zum MCP-Server herstellen, unter APIs und Dienste > OAuth-Zustimmungsbildschirm > Zielgruppe (Testnutzer > + Nutzer hinzufügen) als Testnutzer hinzugefügt.
  • 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, unter der Ihr MCP-Server erreichbar ist (z. B. https://google-ads-mcp-xyz-uc.a.run.app). Da Google Cloud Run diese URL bei der ersten Bereitstellung generiert, sollten Sie die Bereitstellung zuerst ohne diese Variable durchführen und den Dienst dann nach der Bereitstellung aktualisieren.
  • FASTMCP_HOST: Legen Sie hier 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

Bei der Bereitstellung mit --allow-unauthenticated wird die IAM-Prüfung auf Infrastrukturebene von Cloud Run (roles/run.invoker) deaktiviert, sodass externe KI-Clients ohne Google Cloud-Dienstkontotokens eine Verbindung herstellen können. 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, sich zu authentifizieren. Alle Toolanfragen werden ausschließlich unter der OAuth-Identität des authentifizierten Aufrufers ausgeführt.
  • Wenn Sie --allow-unauthenticated weglassen, wird das IAM der Cloud Run-Infrastruktur erzwungen. Aufrufer müssen dann bei jeder Anfrage Google Cloud-OIDC-Identitätstokens übergeben. Da sich Standard-KI-Clients (wie Claude und ChatGPT) über Endnutzer-OAuth und nicht über Google Cloud IAM-Identitätstokens authentifizieren, sind für direkte Verbindungen von diesen Plattformen --allow-unauthenticated mit OAuth auf Anwendungsebene erforderlich.

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 ausgelöst, sich über Google anzumelden und den Bereich 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 Pfad /mcp 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 Clientschlüssel) und achten Sie darauf, dass der Callback-URI des Clients den autorisierten Weiterleitungs-URIs Ihres OAuth-Clients hinzugefügt wird. (Teilnehmer des Pilotprojekts für gehostete Endpunkte, die auf der Zulassungsliste stehen, können auch den Einrichtungsleitfaden für gehostete MCPs lesen.)
  • Clients ohne OAuth-Unterstützung: Clients, die keine HTTP-OAuth-Abläufe unterstützen, erhalten die Antwort „HTTP 401 – Unauthorized“. 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"
    }
  }
}

Kernfunktionen (Tools)

Der Server stellt Tools für die Kontoerkennung 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 GAQL-Anfragen aus, um Ressourcenmesswerte, Budgets und Status abzurufen.

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

    So können Sie die Struktur der Daten und die für Abfragen verfügbaren Felder besser nachvollziehen.

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:

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

Nächste Schritte