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. KI-Agenten können damit Kontodaten abrufen und analysieren, Assets erstellen, Videos hochladen und Labels verwalten, indem sie natürliche Sprache verwenden.

Community-Ressourcen und Support

Technische Übersicht

Durch die Einbindung des Google Ads-MCP-Servers ist es nicht mehr erforderlich, benutzerdefinierten Code für die Google Ads API-Authentifizierung, das Abrufen von Ressourcen, das Parsen von Daten und unterstützte Asset- oder Label-Änderungen zu schreiben. Der Server stellt aufrufbare Tools und Referenz-Ressourcen (siehe Kernfunktionen) bereit, die ein LLM prüfen und aufrufen kann.

Wichtige Spezifikationen

  • Protokoll: MCP (Model Context Protocol)
  • Modus: Lesen und teilweise ändern (Asset-Erstellung, Video-Uploads und Label-Verwaltung mit Vorschlags- und Bestätigungsvalidierung oder konfigurierbarem Lesemodus)
  • Sprache: Python 3.10 oder höher
  • Transport: Standardeingabe/-ausgabe (stdio) oder streamfähiges HTTP (streamable-http in Cloud Run)
  • Authentifizierung: Standardanmeldedaten für Anwendungen (OAuth 2.0-Nutzeranmeldedaten oder Dienstkonto) für lokale stdio oder OAuth 2.0-Webanwendungsanmeldedaten für Remote-HTTP

Funktionsweise der Interaktionsschleife

  1. Anfrage: Sie senden einen Prompt wie „Wie ist die Kampagnenleistung in dieser Woche?“ oder „Erstelle ein Asset mit Zusatzinformationen für unseren Sommerschlussverkauf“.
  2. Erkennung: Das LLM prüft die verfügbaren Tools und Ressourcen und wählt ein passendes google-ads-mcp-Tool aus.
  3. Ausführung oder Probelaufvalidierung: Lesetools fragen die Google Ads API direkt ab. Mutate-Tools werden zuerst im Vorschlagsmodus (validate_only=True) ausgeführt, um Eingaben zu validieren, ohne Änderungen zu übernehmen (siehe Sicherheitsworkflow für Vorschläge und Bestätigungen).
  4. Kontextinjektion: Der MCP-Server gibt strukturierte Abfrageergebnisse oder vorgeschlagene change_items-Einträge und einen Prüf-checksum-Digest an das Kontextfenster des LLM zurück.
  5. Antwort und Bestätigung: Das LLM präsentiert eine Antwort oder bittet Sie, die vorgeschlagenen Änderungen zu bestätigen. Nachdem Sie die Änderung genehmigt haben, ruft das LLM das Mutationstool noch einmal mit validate_only=False und dem entsprechenden checksum-Wert auf, um die Änderung zu übernehmen.

Jetzt starten

So konfigurieren Sie den Google Ads-MCP-Server und führen ihn lokal aus: Wenn Sie stattdessen einen freigegebenen Remotedienst bereitstellen möchten, finden Sie weitere Informationen unter Bereitstellung in Google Cloud.

Vorbereitung

Bevor Sie den Server konfigurieren, müssen Sie die folgenden Voraussetzungen in Ihrer lokalen Umgebung und in der Google Cloud Console erfüllen:

  • Google Cloud-Projekt: Erstellen oder wählen Sie ein Google Cloud-Projekt mit aktivierter Google Ads API aus. Wenn Sie die API aktivieren, erhalten Sie Testzugriff, um Lese- und Änderungs-Workflows für Testkonten zu testen. Wenn Sie auf Produktionskonten zugreifen möchten, prüfen Sie auf der Übersichtsseite der Google Ads API, ob Sie Explorer-, Basic- oder Standardzugriff haben, oder beantragen Sie eine dieser Zugriffsebenen. Andernfalls schlagen Produktionsaufrufe mit dem Fehler AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION fehl. Google stellt Entwicklertokens (GOOGLE_ADS_DEVELOPER_TOKEN) am 9. September 2026 ein. Das Google Cloud-Projekt, zu dem Ihr OAuth-Client oder Ihr Dienstkonto gehört, bestimmt Ihre API-Zugriffsebene.
  • Anmeldedaten: Der lokale stdio-Modus authentifiziert sich mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) aus einer JSON-Datei mit einem OAuth 2.0-Clientschlüssel oder einem Dienstkonto in Ihrem Cloud-Projekt. Legen Sie die Umgebungsvariable GOOGLE_CLOUD_PROJECT fest, wenn Sie Ihr Standardkontingent oder ADC-Projekt angeben müssen. Für Remote-streamable-http-Bereitstellungen sind stattdessen eine Client-ID und ein Clientschlüssel für die OAuth 2.0-Webanwendung erforderlich (siehe In Google Cloud Run bereitstellen).
  • Lokale Software (für den stdio-Modus): Installieren Sie Python 3.10 oder höher, pipx und das gcloud-Befehlszeilentool (zum Generieren von ADC-Dateien für Nutzer).

Konfiguration

  1. Generieren Sie Standardanmeldedaten für Anwendungen (ADC) mit einem OAuth-Client aus Ihrem API-fähigen Google Cloud-Projekt und fügen Sie den Google Ads API-Bereich hinzu:

    gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=PATH_TO_CLIENT_SECRET_JSON

    Ersetzen Sie Folgendes:

    • PATH_TO_CLIENT_SECRET_JSON: der Pfad zur JSON-Datei mit Ihrem OAuth 2.0-Clientschlüssel.

    Dieser Befehl gibt Credentials saved to file: [PATH_TO_CREDENTIALS_JSON] aus (z. B. ~/.config/gcloud/application_default_credentials.json unter Linux und macOS). Wenn Sie sich stattdessen mit einem Dienstkonto authentifizieren möchten, überspringen Sie diesen Schritt und verweisen Sie mit GOOGLE_APPLICATION_CREDENTIALS auf die JSON-Datei Ihres Dienstkontoschlüssels oder übergeben Sie --impersonate-service-account an gcloud auth application-default login.

  2. Fügen Sie den Server der MCP-Konfigurationsdatei Ihres Hosts hinzu (z. B. ~/.gemini/config/mcp_config.json, ~/.gemini/settings.json oder ~/.claude/settings.json):

    {
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "google-ads-mcp==0.0.6",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON"
      }
    }
  }
}

    Ersetzen Sie Folgendes:

    • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
    • PATH_TO_CREDENTIALS_JSON: der Pfad zur JSON-Datei mit den Standardanmeldedaten für Anwendungen, die in Schritt 1 ausgegeben wurde, oder zur JSON-Datei mit dem Dienstkontoschlüssel. Sie können GOOGLE_APPLICATION_CREDENTIALS weglassen, wenn Sie den Standardspeicherort für die ADC-Datei gcloud verwenden.

    Wenn Sie über ein Verwaltungskonto auf Kundenkonten zugreifen möchten, legen Sie GOOGLE_ADS_LOGIN_CUSTOMER_ID (10 Ziffern, ohne Bindestriche) in env fest oder übergeben Sie den Parameter login_customer_id bei einzelnen Toolaufrufen.

Optional: Agenten mit Skills und dem Developer Assistant ausstatten

Der Google Ads-MCP-Server bietet Ihrem KI-Client Live-Zugriff auf Berichtsdaten zum Konto sowie Managementtools zur Asset-Erstellung, zum Hochladen von Videos und zur Labelverwaltung. Kombinieren Sie den MCP-Server mit den folgenden Begleittools, um Ihren KI-Agenten beim Erstellen gültiger Google Ads Query Language (GAQL)-Abfragen und beim Diagnostizieren von Leistungsänderungen im Konto zu unterstützen. Mit diesen Tools wird auch Clientbibliotheks-Code generiert, z. B. Scripts, um erstellte Assets mit Kampagnen zu verknüpfen oder andere nicht unterstützte Änderungen vorzunehmen:

  • Google Ads API-Agent-Skills: Übertragbare Workflow-Module (einschließlich google-ads-api-mcp-setup, google-ads-api-account-diagnostics und google-ads-api-quickstart), mit denen Ihr Agent den Google Ads-MCP-Server mit geringerem Token-Overhead verwenden kann. Führen Sie den folgenden Befehl aus, um sie zu installieren (erfordert Node.js), oder lesen Sie den Leitfaden zu Google Ads API-Agent-Skills für die Einrichtung von Antigravity, Claude Code, Codex und Cursor:

    npx skills add google/skills/skills/ads

  • Google Ads API Developer Assistant: Ein modulares Plug-in für Google Antigravity und Claude Code, das lokale Protobuf-Schemaprüfung, GAQL-Validierung, Codegenerierung für Clientbibliotheken und Fehlerbehebung bei Offline-Conversions bietet. Lesen Sie den Artikel Was ist der Google Ads API Developer Assistant? oder folgen Sie der Installationsanleitung.

Hauptfunktionen

In den folgenden Abschnitten werden die Lesetools, die Tools für partielle Mutationen und die Referenzressourcen des Servers beschrieben. Ab v0.0.6 werden Tools standardmäßig mit dem Namespace-Präfix ihrer Kategorie (z. B. search_search) registriert. Wenn Sie Prompts oder Zulassungslisten von Releases ohne Präfix aktualisieren, müssen Sie die Toolnamen aktualisieren oder ein leeres Präfix ("") in tools_config.yaml festlegen (siehe Tool-Namespaces und Lesemodus konfigurieren).

Lesetools

  • customers_list_accessible_customers (Tool list_accessible_customers): Gibt die Google Ads-Kundennummern zurück, auf die der authentifizierte Nutzer direkt zugreifen kann.
  • search_search (Tool search): Erstellt und führt GAQL-SearchStream-Abfragen aus strukturierten Parametern (customer_id, resource und fields sowie optional conditions, orderings, limit und login_customer_id) anstelle eines unbearbeiteten GAQL-Strings aus. An jede Abfrage wird PARAMETERS omit_unselected_resource_names=true angehängt, um Ressourcenattribute, Messwerte, Segmente, Budgets und Status sauber abzurufen.
  • metadata_get_resource_metadata (Tool get_resource_metadata): Ruft auswählbare, filterbare und sortierbare Attribute, Messwerte und Segmente für einen Google Ads API-Ressourcentyp ab (z. B. "campaign"). Verwenden Sie diese Metadaten, um gültige Abfragefelder zu ermitteln, einschließlich Messwerten und Segmenten, die in Nebenversionen wie v26.2 hinzugefügt wurden, bevor Sie das Tool search_search aufrufen.

Mutate-Tools (teilweise Unterstützung)

  • assets_create_asset (Tool create_asset): Erstellt eigenständige Google Ads-Assets mit dedizierten Parametern für die Asset-Typen TEXT, IMAGE, YOUTUBE_VIDEO, SITELINK, CALLOUT und STRUCTURED_SNIPPET. Übergeben Sie das extra_params-Wörterbuch für andere änderbare AssetService-Typen (z. B. PRICE, PROMOTION, CALL oder BUSINESS_MESSAGE) und fügen Sie final_urls auf Stammebene neben sitelink_link_text für SITELINK-Assets hinzu. Lokale Dateipfade (image_asset_path) funktionieren nur im lokalen stdio-Modus. Übergeben Sie bei Remote-HTTP-Bereitstellungen den base64-codierten Parameter image_asset_data, wobei image_asset_mime_type auf IMAGE_PNG, IMAGE_JPEG oder IMAGE_GIF (bis zu 20 MB) festgelegt ist.
  • assets_upload_video_asset (Tool upload_video_asset): Lädt eine lokale Videodatei (.3gp, .avi, .flv, .mkv, .mov, .mp4, .mpeg, .mpg, .ogg, .webm oder .wmv) über die Google Ads API nur im lokalen stdio-Modus auf YouTube hoch. Sowohl video_title als auch video_description sind erforderliche Parameter. Die Datenschutzeinstellung ist standardmäßig auf UNLISTED festgelegt (oder auf PUBLIC bei Markenkanälen, die dem Werbetreibenden gehören, mit Nutzer-OAuth). Dieses Tool gibt einen Google Ads-video_upload_id-Wert (und Ressourcennamen) zurück, nicht die 11-stellige YouTube-video_id. Fragen Sie you_tube_video_upload mit dem Tool search_search ab (Filtern nach you_tube_video_upload.video_upload_id), bis you_tube_video_upload.state = 'PROCESSED'. Übergeben Sie dann you_tube_video_upload.video_id als Parameter youtube_video_id an assets_create_asset (asset_type="YOUTUBE_VIDEO").
  • labels_manage_labels (Tool manage_labels): Erstellt, aktualisiert und entfernt Kontolabels, einschließlich Name, Beschreibung und Hex-Hintergrundfarbe.
  • labels_manage_label_associations (Tool manage_label_associations): Unterstützt die Labelzuordnungsvorgänge CREATE und REMOVE (UPDATE wird nicht unterstützt) für die Ressourcen CAMPAIGN, CUSTOMER, AD_GROUP und AD_GROUP_CRITERION. Für CUSTOMER-Ressourcen ist resource_id optional und standardmäßig auf customer_id festgelegt. Übergeben Sie eine zusammengesetzte {ad_group_id}~{criterion_id}-ID für AD_GROUP_CRITERION-Ressourcen und entfernen Sie Verknüpfungen, indem Sie entweder resource_id und label_id oder association_resource_name übergeben. AD_GROUP_AD-Labels auf Anzeigenebene werden nicht unterstützt.

Referenzressourcen

Der Server stellt vier schreibgeschützte MCP-Ressourcen bereit, die unabhängig von Ihren tools_config.yaml-Einstellungen bereitgestellt bleiben:

  • resource://discovery-document: JSON-REST-Discovery-Übersicht über Google Ads API-Ressourcen, -Dienstmethoden und -Schemas. Es ergänzt das metadata_get_resource_metadata-Tool, das auswählbare, filterbare und sortierbare GAQL-Abfragefelder zurückgibt.
  • resource://metrics: HTML-Referenzdokumentation für Google Ads API-Messwerte.
  • resource://segments: HTML-Referenzdokumentation für Google Ads API-Segmente.
  • resource://release-notes: HTML-Versionshinweise zur Google Ads API mit Versionsänderungen und neuen Funktionen.

Workflow für Vorschläge und Bestätigungen zur Sicherheit

Bei jedem Änderungstool (assets_create_asset, assets_upload_video_asset, labels_manage_labels und labels_manage_label_associations) wird ein zweistufiger Vorschlags- und Bestätigungsworkflow erzwungen, um unbeabsichtigte Kontoänderungen zu verhindern:

  1. Vorschlagen (validate_only=True, Standard): Validiert Eingaben, ohne Änderungen zu übernehmen. Die Asset- und Label-Tools führen einen Live-Probelauf der Google Ads API (validate_only) aus. Da YouTubeVideoUploadService keinen Probelaufmodus hat, validiert assets_upload_video_asset stattdessen die lokale Datei und bindet ihre Größe und den Änderungszeitstempel. Jedes Tool gibt menschenlesbare change_items-Einträge und einen zustandslosen SHA-256-checksum-Digest zurück, der an den customer_id-Parameter und die Anfrage-Nutzlast gebunden ist.
  2. Bestätigen (validate_only=False): Nachdem der Agent die Liste change_items präsentiert und Ihre Genehmigung erhalten hat, ruft er das Tool noch einmal mit validate_only=False, dem identischen Parameter und den Argumenten customer_id und dem Wert checksum aus Schritt 1 auf. Der Server lehnt fehlende oder nicht übereinstimmende Prüfsummen ab, bevor das Konto geändert wird.

Tool-Namespaces und Lesemodus konfigurieren

Der Server enthält eine Standarddatei tools_config.yaml, in der alle fünf Toolkategorien (customers, search, metadata, labels und assets) aktiviert sind. Sie können tools_config.yaml anpassen, um einzelne Tools oder Namespaces selektiv zu aktivieren oder zu deaktivieren, Namespace-Präfixe zu ändern oder zu entfernen oder eine rein schreibgeschützte Bereitstellung zu erzwingen.

Beim Start löst der Server tools_config.yaml in der folgenden Reihenfolge auf:

  1. Ein expliziter Pfad in der Umgebungsvariablen GOOGLE_ADS_MCP_TOOLS_CONFIG (empfohlen für lokale stdio-Hosts, deren Arbeitsverzeichnis sich von Ihrem Projektordner unterscheiden kann).
  2. Eine tools_config.yaml-Datei im aktuellen Arbeitsverzeichnis des Servers.
  3. Die Standarddatei tools_config.yaml, die im Paket enthalten ist.

Wenn GOOGLE_ADS_MCP_TOOLS_CONFIG auf eine fehlende Datei verweist oder eine aufgelöste Konfigurationsdatei ungültig ist, gibt der Server beim Start einen Fehler aus, anstatt auf die Standardeinstellungen zurückzugreifen.

Die folgende minimale tools_config.yaml-Datei erzwingt ein Deployment, das nur Lesezugriff hat:

namespaces:
  customers: true
  search: true
  metadata: true
  labels: false
  assets: false

In der folgenden tools_config.yaml-Datei werden Präfixe angepasst und einzelne Tools gefiltert. Beispielsweise wird das Base64-Tool create_asset in Cloud Run verfügbar gemacht, während das nur lokal verfügbare Tool upload_video_asset deaktiviert wird:

namespaces:
  # Default prefix ("customers_list_accessible_customers")
  customers: true

  # Empty prefix mounts unprefixed tool names ("search")
  search: ""

  # Custom prefix ("schema_get_resource_metadata")
  metadata: "schema"

  # Enable only specific tools in a multi-tool category
  assets:
    enabled_tools:
      - create_asset

Beispiel-Prompts für den Einstieg

Probieren Sie die folgenden Prompts in Ihrem MCP-Client aus, nachdem Sie den Server verbunden haben.

Fragen, was der Server tun kann

What can the google-ads-mcp server do?

Nach Kunden fragen

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

Assets erstellen, Videos hochladen und Labels verwalten

Create a callout asset with the text "Free Shipping" for account 1234567890

Upload /path/to/promo.mp4 with title "Summer Sale" and description "Summer promo video" for account 1234567890

Create a label named "Q4 Promo" with background color #34A853 and apply it to campaign 9876543210 in account 1234567890

Bereitstellung in Google Cloud

Wenn Sie den MCP-Server für mehrere Agenten freigeben oder als Webdienst ausführen möchten, hosten Sie ihn in Google Cloud Run oder bei einem anderen Cloud-Infrastrukturanbieter, anstatt ihn lokal auszuführen.

Vorbereitung

  1. Ein Google Cloud-Projekt mit aktivierter Google Ads API (Informationen zu den Anforderungen für den Produktionszugriff finden Sie unter Voraussetzungen).

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

    gcloud config set project PROJECT_ID

    Ersetzen Sie Folgendes:

    • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.

Docker-Image erstellen und per Push übertragen

Verwenden Sie Cloud Build, um das Container-Image zu erstellen und in Artifact Registry zu übertragen, ohne Docker lokal zu installieren:

  1. Erstellen Sie ein Repository in Artifact Registry:

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

  2. Erstellen Sie das Image und senden Sie es über ein Release-Tag im GitHub-Repository (oder über . in einem lokalen Checkout, wenn Sie Dockerfile oder tools_config.yaml angepasst haben):

    gcloud builds submit https://github.com/googleads/google-ads-mcp \
  --git-source-revision=v0.0.6 \
  --tag=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6

    Ersetzen Sie Folgendes:

    • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.

    Erstellen Sie das Image neu und stellen Sie es erneut bereit, wenn Sie google-ads-mcp aktualisieren oder die gebündelte Python-Clientbibliothek google-ads für neue Google Ads API-Releases (z. B. v26.2) aktualisieren.

In Google Cloud Run bereitstellen

Konfigurieren Sie die folgenden Umgebungsvariablen und Secrets für Ihren Cloud Run-Dienst:

  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Die OAuth 2.0-Client-ID für Webanwendungen aus Ihrem API-fähigen Google Cloud-Projekt für die OAuth-Authentifizierung auf Anwendungsebene. Führen Sie die folgenden OAuth-Konfigurationsschritte aus:
    • Fügen Sie die autorisierten Weiterleitungs-URIs für alle KI-Clients hinzu, 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).
    • Fügen Sie den Bereich https://www.googleapis.com/auth/adwords auf dem OAuth-Zustimmungsbildschirm unter APIs und Dienste > OAuth-Zustimmungsbildschirm > Datenzugriff (Bereiche hinzufügen oder entfernen) hinzu.
    • Wenn der Veröffentlichungsstatus Ihres OAuth-Zustimmungsbildschirms auf Test (Standard) festgelegt ist, fügen Sie die Google-Konten, die eine Verbindung zum MCP-Server herstellen, unter APIs und Dienste > OAuth-Zustimmungsbildschirm > Zielgruppe (Testnutzer > + Nutzer hinzufügen) als Testnutzer hinzu.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Der OAuth-Clientschlüssel, der Ihrer OAuth-Client-ID entspricht.
  • GOOGLE_ADS_MCP_BASE_URL: Die öffentliche Basis-URL Ihres MCP-Servers (z. B. https://google-ads-mcp-xyz-uc.a.run.app). Cloud Run weist diese URL während der ersten Bereitstellung zu. Stellen Sie den Dienst daher zuerst ohne diese Variable bereit und aktualisieren Sie ihn anschließend.
  • GOOGLE_ADS_MCP_JWT_SIGNING_KEY (empfohlen für Cloud Run mit mehreren Instanzen): Ein persistentes Secret, das FastMCP-JWTs über Containerneustarts und horizontales Skalieren hinweg signiert.
  • GOOGLE_ADS_MCP_STORAGE_TYPE (empfohlen für Cloud Run mit mehreren Instanzen): Persistentes Backend für OAuth-Clientregistrierungen und -Tokens (redis mit GOOGLE_ADS_MCP_STORAGE_REDIS_URL oder firestore). Da die Standard-v0.0.6-Dockerfile nur das In-Memory-Backend installiert, installieren Sie zuerst py-key-value-aio[redis] oder .[firestore] in einer benutzerdefinierten Dockerfile. Für die Verwendung von firestore sind außerdem eine Firestore-Datenbank und die IAM-Rolle roles/datastore.user für das Cloud Run-Dienstkonto erforderlich. Übergeben Sie für Tests mit einer einzelnen Instanz mit speicherinternem Speicher --max-instances=1.
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID (optional): Standardmäßige 10-stellige Kundennummer des Verwaltungskontos (ohne Bindestriche), die verwendet wird, wenn der Parameter login_customer_id bei Toolaufrufen weggelassen wird.
  • GOOGLE_ADS_MCP_TOOLS_CONFIG (optional): Containerpfad zu einer benutzerdefinierten tools_config.yaml-Datei (z. B. aus Secret Manager unter /etc/mcp/tools_config.yaml bereitgestellt, um den Lesemodus ohne Neuerstellung des Images zu erzwingen). Weitere Informationen finden Sie unter Tool-Namespaces und Lesemodus konfigurieren.

Speichern Sie GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET und GOOGLE_ADS_MCP_JWT_SIGNING_KEY in Secret Manager und stellen Sie den Dienst in Google Cloud Run bereit:

gcloud run deploy google-ads-mcp \
  --image=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6 \
  --platform=managed \
  --region=us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=CLIENT_ID" \
  --set-secrets="GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=MCP_OAUTH_CLIENT_SECRET:latest,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=MCP_JWT_SIGNING_KEY:latest"

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://CLOUD_RUN_SERVICE_URL"

Ersetzen Sie Folgendes:

  • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
  • CLIENT_ID: Ihre OAuth 2.0-Client-ID für die Webanwendung.
  • MCP_OAUTH_CLIENT_SECRET: der Secret Manager-Secret-Name, unter dem Ihr OAuth 2.0-Clientschlüssel gespeichert ist.
  • MCP_JWT_SIGNING_KEY: der Secret Manager-Secret-Name, unter dem Ihr JWT-Signaturschlüssel gespeichert ist.
  • CLOUD_RUN_SERVICE_URL: der Hostname, der Ihrem Cloud Run-Dienst zugewiesen ist (z. B. google-ads-mcp-xyz-uc.a.run.app).

Authentifizierungs- und Sicherheitsmodell

Bei der Bereitstellung mit --allow-unauthenticated wird die IAM-Prüfung der Cloud Run-Infrastruktur (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 festgelegt sind, erzwingt der Server bei jeder Anfrage Google OAuth 2.0 und gibt den HTTP-Statuscode 401 Unauthorized an nicht authentifizierte Aufrufer zurück. Jeder Toolaufruf wird unter der OAuth-Identität des authentifizierten Aufrufers ausgeführt.
  • Wenn Sie --allow-unauthenticated weglassen, müssen Aufrufer bei jeder Anfrage Google Cloud-OIDC-Identitätstokens übergeben. Standard-KI-Clients (wie Claude und ChatGPT) verwenden OAuth für Endnutzer anstelle von Google Cloud IAM-Tokens. Daher sind für direkte Verbindungen --allow-unauthenticated in Kombination mit OAuth auf Anwendungsebene erforderlich.

MCP-Client konfigurieren

Konfigurieren Sie nach der Bereitstellung Ihren MCP-Client mit der Cloud Run-Dienst-URL. Da der Server OAuth 2.0 erzwingt, muss Ihr 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 eine Aufforderung von Google zur Anmeldung ausgelöst, um den Zugriffsbereich https://www.googleapis.com/auth/adwords zu gewähren (in der Google Cloud Console als .../auth/adwords angezeigt).
  • KI-Plattformen von Drittanbietern (Claude, ChatGPT): Fügen Sie in den Connector-Einstellungen Ihres Clients einen benutzerdefinierten Connector hinzu, der auf Ihre Dienst-URL mit dem Pfad /mcp verweist (z. B. https://google-ads-mcp-xyz-uc.a.run.app/mcp). Wählen Sie die OAuth 2.0-Authentifizierung mit Ihrer OAuth-Client-ID und Ihrem Clientschlüssel aus und prüfen Sie, ob der Callback-URI des Clients in den autorisierten Weiterleitungs-URIs Ihres OAuth-Clients enthalten ist.
  • Clients ohne OAuth-Unterstützung: Clients, die keine HTTP-OAuth-Abläufe unterstützen, erhalten den HTTP-Statuscode 401 Unauthorized. Verwenden Sie für diese Clients stattdessen die lokale stdio-Konfiguration.

Im folgenden Beispiel wird das gemini-Befehlszeilentool in ~/.gemini/settings.json konfiguriert. Ersetzen Sie für Google Antigravity in ~/.gemini/config/mcp_config.json "httpUrl" durch "serverUrl" oder "url":

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://CLOUD_RUN_SERVICE_URL/mcp"
    }
  }
}

Ersetzen Sie Folgendes:

  • CLOUD_RUN_SERVICE_URL: der Hostname, der Ihrem Cloud Run-Dienst zugewiesen ist (z. B. google-ads-mcp-xyz-uc.a.run.app).

Nächste Schritte