Google Ads MCP Server

Dieses Repository enthält den Quellcode für einen MCP-Server, der mit der Google Ads API interagiert.

Tools

Der Server verwendet die Google Ads API, um mehrere Tools und Ressourcen für die Verwendung mit LLMs und KI-Agenten bereitzustellen.

Verfügbare Tools

• search: Ruft Informationen über das Google Ads-Konto ab.

• get_resource_metadata: Ruft Metadaten über einen Google Ads API-Ressourcentyp ab, z. B. „campaign“. Dies ist nützlich, um die Struktur der Daten und die verfügbaren Felder für Abfragen zu verstehen.

• list_accessible_customers: Gibt die IDs der Kunden zurück, auf die der den Aufruf authentifizierende Benutzer direkt zugreifen kann.

Konfigurieren und Namespacing von Tools

Der Google Ads MCP Server verwendet die tools_config.yaml, um Ihnen die selektive Aktivierung oder Deaktivierung einzelner Tools oder Tool-Kategorien (Namespaces) sowie die Anpassung ihrer Namespace-Präfixe zu ermöglichen.

Eine standardmäßige tools_config.yaml mit allen aktivierten Tools ist im Paket enthalten, sodass der Server ohne zusätzliche Einrichtung sofort einsatzbereit ist. Um Ihre Installation anzupassen, löst der Server die Konfiguration in der folgenden Reihenfolge auf:

1. Ein expliziter Pfad, der über die Umgebungsvariable GOOGLE_ADS_MCP_TOOLS_CONFIG festgelegt wurde.

2. Eine tools_config.yaml-Datei im aktuellen Arbeitsverzeichnis.

3. Die standardmäßige tools_config.yaml, die im Paket enthalten ist.

Wenn eine explizit angeforderte Konfigurationsdatei (über die Umgebungsvariable) fehlt oder eine aufgelöste Datei ungültig ist, gibt der Server einen Fehler aus und startet nicht.

Konfigurationsbeispiel:

namespaces:
  # Option 1: Enable category 'customers' with default prefix -> "customers_list_accessible_customers"
  customers: true

  # Option 2: Enable category 'search' with a custom prefix -> "query_search"
  search: "query"

  # Option 3: Fine-grained control over tools in a category
  metadata:
    enabled: true
    prefix: "metadata"
    enabled_tools:
      - get_resource_metadata: true

Verfügbare Ressourcen

• discovery-document: Ruft das Google Ads API Discovery-Dokument ab. Stellt das Discovery-Dokument für die neueste Version der Google Ads API bereit, das die API-Oberfläche einschließlich Ressourcen, Methoden und Schemata beschreibt. Host-LLMs sollten auf diese Ressource zugreifen, um die Struktur der Google Ads API zu verstehen und verfügbare Funktionen zu entdecken.

• metrics: Ruft Informationen über die für die Berichterstellung in der Google Ads API verfügbaren Metriken ab.

• segments: Ruft Informationen über die für die Berichterstellung in der Google Ads API verfügbaren Segmente ab.

• release-notes: Ruft die Versionshinweise für die neueste Version der Google Ads API ab.

Related MCP server: gads

Hinweise

1. Der MCP Server gibt Ihre Daten an den Agenten oder das LLM weiter, mit dem Sie ihn verbinden.

2. Bei technischen Problemen nutzen Sie bitte den GitHub Issue Tracker.

3. Um uns bei der Erfassung von Nutzungsdaten zu helfen, werden Sie einen zusätzlichen Header in Ihren API-Aufrufen bemerken: Diese Daten werden zur Verbesserung des Produkts verwendet.

Einrichtungsanleitung

Die Einrichtung umfasst die folgenden Schritte:

1. Python konfigurieren.

2. Entwickler-Token konfigurieren.

3. APIs in Ihrem Projekt aktivieren.

4. Anmeldedaten konfigurieren.

5. Ihren MCP-Client konfigurieren.

Python konfigurieren

Installieren Sie pipx.

Entwickler-Token konfigurieren

Befolgen Sie die Anweisungen zum Erhalten eines Entwickler-Tokens.

Ihr Entwickler-Token muss mindestens über Explorer-Zugriff verfügen, um Produktionskonten abfragen zu können. Neue Token werden möglicherweise automatisch auf Explorer-Zugriff hochgestuft; falls nicht, können Sie über das API Center einen Antrag stellen. Weitere Informationen finden Sie in der Dokumentation zu Zugriffsstufen.

Wenn Sie den Fehler "The developer token is only approved for use with test accounts" sehen, hat Ihr Token noch keinen Zugriff auf Produktionskonten. Informationen zur Beantragung der benötigten Zugriffsstufe finden Sie in der Dokumentation zu Zugriffsstufen.

APIs in Ihrem Projekt aktivieren

Befolgen Sie die Anweisungen, um die folgenden APIs in Ihrem Google Cloud-Projekt zu aktivieren:

• Google Ads API

Anmeldedaten konfigurieren

Option 1: Verwendung des FastMCP OAuth Proxy

Der Server unterstützt die OAuth-Proxy-Funktion von FastMCP für die dynamische Benutzerauthentifizierung. Dies ist nützlich, wenn der Server als Webdienst ausgeführt wird.

Um dies zu aktivieren, setzen Sie die folgenden Umgebungsvariablen:

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Ihre Google Cloud OAuth 2.0-Client-ID.

• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Ihr Google Cloud OAuth 2.0-Client-Geheimnis.

• GOOGLE_ADS_MCP_BASE_URL: (Optional) Die Basis-URL, unter der der Server erreichbar ist (Standardwert: http://localhost:8080).

• GOOGLE_ADS_MCP_JWT_SIGNING_KEY: (Optional) Geheimer Schlüssel zum Signieren von FastMCP JWT-Tokens über mehrere Serverinstanzen oder Bereitstellungen hinweg.

• GOOGLE_ADS_MCP_STORAGE_TYPE: (Optional) Speicher-Backend für den OAuth-Status (filetree, redis, firestore oder memory).

• GOOGLE_ADS_MCP_STORAGE_PATH: (Optional) Verzeichnispfad für den dauerhaften filetree-Speicher.

• GOOGLE_ADS_MCP_STORAGE_REDIS_URL: (Optional) Redis-URL für den dauerhaften redis-Speicher.

• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_PROJECT: (Optional) Google Cloud-Projekt für den dauerhaften firestore-Speicher. Standardmäßig wird das aus den Application Default Credentials abgeleitete Projekt verwendet. Die Einstellung wählt das firestore-Backend aus, auch wenn GOOGLE_ADS_MCP_STORAGE_TYPE nicht gesetzt ist.

• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_DATABASE: (Optional) Firestore-Datenbankname für den dauerhaften firestore-Speicher. Standardwert: (default).

• GOOGLE_ADS_MCP_STORAGE_ENCRYPTION_KEY: (Optional) Verschlüsselungsschlüssel für gespeicherte OAuth-Tokens.

• GOOGLE_ADS_MCP_STORAGE_DISABLE_ENCRYPTION: (Optional) Auf true setzen, um die Token-Verschlüsselung zu deaktivieren.

Die Backends redis und firestore benötigen die Installation ihrer Speicherbibliothek zusammen mit dem Server: pip install py-key-value-aio[redis] bzw. pip install google-ads-mcp[firestore].

Sobald dies aktiviert ist, können Sie sich über Ihren MCP-Client bei der API authentifizieren.

Wenn diese Variablen gesetzt sind, wechselt der Server automatisch zum streamable-http-Transport (SSE/HTTP) anstelle von stdio.

Sie müssen den Server als separaten Prozess ausführen und Ihren MCP-Client so konfigurieren, dass er eine Verbindung zum SSE-Endpunkt herstellt (z. B. http://localhost:8080/mcp).

Option 2: Anmeldedaten mit Application Default Credentials konfigurieren

Konfigurieren Sie Ihre Application Default Credentials (ADC). Stellen Sie sicher, dass die Anmeldedaten für einen Benutzer mit Zugriff auf Ihre Google Ads-Konten oder -Eigenschaften sind.

Die Anmeldedaten müssen den Google Ads API-Bereich enthalten:

https://www.googleapis.com/auth/adwords

Informationen zum Erstellen eines OAuth-Clients finden Sie unter OAuth-Clients verwalten.

Hier sind einige Beispiel-gcloud-Befehle, die Sie nützlich finden könnten:

• ADC mit Benutzeranmeldedaten und einem OAuth-Desktop- oder Web-Client einrichten, nachdem Sie das Client-JSON in YOUR_CLIENT_JSON_FILE heruntergeladen haben.

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

• ADC mithilfe der Dienstkonto-Impersonierung einrichten.

  gcloud auth application-default login \
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
    --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform

Wenn der Befehl gcloud auth application-default abgeschlossen ist, kopieren Sie den Speicherort der Datei PATH_TO_CREDENTIALS_JSON, der in der folgenden Nachricht auf der Konsole ausgegeben wird. Sie benötigen dies für einen späteren Schritt!

Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]

Option 3: Anmeldedaten mit der Python-Clientbibliothek der Google Ads API konfigurieren.

Befolgen Sie die Anweisungen, um die Python-Clientbibliothek der Google Ads API einzurichten und zu konfigurieren.

Wenn Sie dies bereits getan haben und eine funktionierende google-ads.yaml besitzen, können Sie diese Datei wiederverwenden!

Ändern Sie in der Datei utils.py die Methode get_googleads_client() so, dass sie die Methode load_from_storage() verwendet.

Ihren MCP-Client konfigurieren

Fügen Sie den Server zur Konfiguration Ihres MCP-Clients hinzu. Nachfolgend finden Sie Beispiele für gängige Clients.

Antigravity CLI / Antigravity Code Assist

1. Installieren Sie Antigravity CLI oder Antigravity Code Assist.

2. Konfigurieren Sie Ihren Server. Details zur Einrichtung von MCP-Servern finden Sie in der Dokumentation unter https://antigravity.google/docs/mcp.

• Option 1: Verwendung des FastMCP OAuth Proxy (Streamable HTTP)

  Sie können den Server als separaten Prozess ausführen und Ihren MCP-Client so konfigurieren, dass er eine Verbindung zum SSE-Endpunkt herstellt (z. B. http://localhost:8080/mcp). Dies ermöglicht auch die Verwendung der OAuth-Proxy-Funktion von FastMCP für die dynamische Benutzerauthentifizierung.

  {
    "mcpServers": {
      "google-ads-mcp": {
        "httpUrl":"http://localhost:8080/mcp",
        "env": {
          "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"                        
        }
      }
    }
  }

• Option 2: Die Methode mit Application Default Credentials

  Ersetzen Sie PATH_TO_CREDENTIALS_JSON durch den Pfad, den Sie im vorherigen Schritt kopiert haben.

  Wir empfehlen außerdem, dem Objekt env ein Attribut GOOGLE_CLOUD_PROJECT hinzuzufügen. Ersetzen Sie YOUR_PROJECT_ID im folgenden Beispiel durch die Projekt-ID Ihres Google Cloud-Projekts.

  {
    "mcpServers": {
      "google-ads-mcp": {
        "command": "pipx",
        "args": [
          "run",
          "--spec",
          "git+https://github.com/googleads/google-ads-mcp.git",
          "google-ads-mcp"
        ],
        "env": {
          "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
          "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
        }
      }
    }
  }

• Option 3: Die Methode mit der Python-Clientbibliothek

  {
    "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_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
        }
      }
    }
  }

Kunden-ID für die Anmeldung

Wenn Ihr Zugriff auf das Kundenkonto über ein Verwaltungskonto erfolgt, müssen Sie die Kunden-ID des Verwaltungskontos zur Einstellungsdatei hinzufügen.

Details finden Sie hier.

Die endgültige Datei sieht wie folgt aus:

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_CUSTOMER_ID"
      }
    }
  }
}

Andere MCP-Clients (Claude Code, Cursor, VS Code usw.)

Das Format des Blocks mcpServers ist bei allen MCP-Clients gleich. Fügen Sie die oben gezeigte Konfiguration zur entsprechenden Einstellungsdatei Ihres Clients hinzu (z. B. ~/.claude/settings.json für Claude Code, .cursor/mcp.json für Cursor, .vscode/mcp.json für VS Code mit Copilot).

Bereitstellung auf Google Cloud Platform

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

Beachten Sie, dass dies nur die Authentifizierung mit einem OAuth-Client-ID- und Client-Geheimnis-Paar über den OAuth-Proxy (Option #1 oben) unterstützt.

Voraussetzungen

1. Ein Google Cloud-Projekt.

2. Die gcloud CLI ist installiert, authentifiziert und das aktive Projekt ist gesetzt.

   gcloud config set project YOUR_PROJECT_ID

Schritt 1: Docker-Image erstellen und pushen

Sie können Cloud Build verwenden, um das Image zu erstellen und in Artifact Registry zu pushen, ohne dass Docker lokal installiert sein muss.

1. Erstellen Sie ein Repository in Artifact Registry:

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

2. Erstellen und übermitteln Sie das Image:

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

   Ersetzen Sie YOUR_PROJECT_ID durch Ihre Google Cloud-Projekt-ID.

Schritt 2: Auf Google Cloud Run bereitstellen

Stellen Sie sicher, dass die erforderlichen Umgebungsvariablen gesetzt sind:

• GOOGLE_PROJECT_ID: Ihre Google Cloud-Projekt-ID.

• GOOGLE_ADS_DEVELOPER_TOKEN: Das Entwickler-Token, das der MCP-Server verwenden soll (siehe oben).

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Die OAuth-Client-ID, die der MCP-Server verwenden soll.

• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Das OAuth-Client-Geheimnis, das der MCP-Server verwenden soll.

• GOOGLE_ADS_MCP_BASE_URL: Die Basis-URL, unter der Ihr MCP-Server erreichbar ist: Diese wird nach der ersten Bereitstellung automatisch von Google Cloud Run zugewiesen. Sie können die Umgebungsvariablen nach der Bereitstellung aktualisieren.

• GOOGLE_ADS_MCP_JWT_SIGNING_KEY: (Empfohlen für die Produktion) Persistenter JWT-Signierschlüssel über Cloud Run-Instanzen hinweg.

• GOOGLE_ADS_MCP_STORAGE_TYPE: (Empfohlen für die Produktion) Speicher-Backend zum Persistieren von OAuth-Tokens über Instanzen hinweg. Setzen Sie es auf firestore, um Firestore über die Standardanmeldeinformationen der Anwendung zu verwenden, was keinen VPC-Connector benötigt, oder auf redis zusammen mit GOOGLE_ADS_MCP_STORAGE_REDIS_URL.

  Die Verwendung von firestore erfordert drei Dinge: Erstellen Sie das Image mit der zusätzlichen Installation (ändern Sie die Dockerfile in uv pip install --system .[firestore]), erstellen Sie eine Firestore-Datenbank im Projekt, da diese nicht automatisch bereitgestellt wird, und gewähren Sie dem Cloud Run-Dienstkonto die Rolle roles/datastore.user. Beachten Sie, dass Einträge nicht automatisch ablaufen: Der Speicher filtert abgelaufene Einträge beim Lesen, löscht sie jedoch nie, und expires_at wird als Zeichenfolge geschrieben, sodass eine Firestore-TTL-Richtlinie sie ebenfalls nicht einsammeln kann. Planen Sie für langlebige Bereitstellungen einen regelmäßigen Bereinigungsauftrag ein. Redis läuft Einträge von selbst ab.

• FASTMCP_HOST: Setzen Sie dies auf 0.0.0.0, um FastMCP zu erlauben, Verbindungen von allen IP-Adressen zu akzeptieren.

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_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,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,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=YOUR_JWT_SIGNING_KEY,GOOGLE_ADS_MCP_STORAGE_TYPE=firestore,FASTMCP_HOST=0.0.0.0"

Schritt 3: MCP-Client konfigurieren

Aktualisieren Sie nach der Bereitstellung Ihre MCP-Client-Konfiguration (siehe die Dokumentation unter https://antigravity.google/docs/mcp), um die Cloud Run-URL zu verwenden.

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

Testen Sie es

Starten Sie Ihren MCP-Client. Sie sollten google-ads-mcp in der Liste der verfügbaren Server sehen.

Hier sind einige Beispielaufforderungen für den Einstieg:

• Fragen Sie, was der Server kann:

  what can the ads-mcp server do?

• Fragen Sie nach Kunden:

  what customers do I have access to?

• Fragen Sie nach Kampagnen:

  How many active campaigns do I have?

  How is my campaign performance this week?

Hinweis zur Kunden-ID

Ihr Agent wird für die meisten Aufforderungen eine Kunden-ID benötigen und danach fragen. Wenn Sie zwischen mehreren Kunden wechseln, kann es einfacher sein, die Kunden-ID in die Aufforderung aufzunehmen.

How many active campaigns do I have for customer id 1234567890

Mitwirken

Beiträge sind willkommen! Siehe den Leitfaden zum Mitwirken.