Serwer MCP Google Ads: przewodnik po integracji dla programistów

Model Context Protocol (MCP) to otwarty standard, który umożliwia dużym modelom językowym (LLM) bezpieczne interakcje z zewnętrznymi danymi i aplikacjami. Serwer Google Ads MCP zapewnia standardowy pomost do interfejsu Google Ads API, który umożliwia agentom AI analizowanie i pobieranie danych kampanii w języku naturalnym.

Materiały i pomoc społeczności

  • Repozytorium GitHub: w repozytorium google-ads-mcp znajdziesz prezentacje, przykłady oraz możesz zgłaszać błędy i sugerować funkcje.

    Do zgłaszania błędów i przesyłania próśb o dodanie funkcji używaj karty Issues.

  • Społeczność: dołącz do kanału #ads-api-ai-tools na Discordzie społeczności Google Advertising.

Informacje techniczne

Wdrożenie tego serwera MCP eliminuje konieczność pisania niestandardowego „kodu łączącego” na potrzeby uwierzytelniania w interfejsie Google Ads API, pobierania zasobów i analizowania danych. Serwer udostępnia konkretne narzędzia , które LLM może samodzielnie wykrywać i wywoływać.

Najważniejsze specyfikacje

  • Protokół: MCP (Model Context Protocol)
  • Tryb: Tylko do odczytu (obecna wersja)
  • Język: Python
  • Transport: standardowe wejście/wyjście (stdio) lub HTTP z możliwością przesyłania strumieniowego (streamable-http / Cloud Run)
  • Uwierzytelnianie: OAuth 2.0 lub konto usługi

Jak działa pętla interakcji

  1. Żądanie: użytkownik przesyła zapytanie, np. „Jak w tym tygodniu radzi sobie moja kampania?”.
  2. Wykrywanie: LLM sprawdza dostępne narzędzia i identyfikuje możliwości wyszukiwania google-ads-mcp.
  3. Wykonanie: serwer MCP wykonuje podstawową logikę Pythona, aby wysłać zapytanie do interfejsu Google Ads API.
  4. Wstawianie kontekstu: ustrukturyzowane wyniki są zwracane do okna kontekstu LLM.
  5. Odpowiedź: LLM syntetyzuje dane w odpowiedź zrozumiałą dla człowieka.

Rozpocznij

Aby skonfigurować serwer Google Ads MCP i zacząć go używać, wykonaj te czynności.

Wymagania wstępne

Przed konfiguracją upewnij się, że masz w konsoli Google Cloud te dane logowania:

  • Identyfikator projektu: identyfikator projektu Google Cloud (GOOGLE_PROJECT_ID). Sprawdź stronę przeglądu interfejsu Google Ads API, aby upewnić się, że Twój projekt ma poziom dostępu Eksplorator, Podstawowy lub Standardowy. Jeśli nie, poproś o jeden z tych poziomów dostępu. Pamiętaj, że tokeny programisty (GOOGLE_ADS_DEVELOPER_TOKEN) zostały wycofane 9 września 2026 r. i nie są już wymagane w najnowszej wersji serwera Google Ads MCP, ponieważ poziomy dostępu do interfejsu API są powiązane z projektem Google Cloud.
  • Dane uwierzytelniające OAuth: para identyfikator klienta/tajny klucz klienta OAuth 2.0 lub zestaw domyślnych danych logowania aplikacji.

Konfiguracja

Aby zintegrować serwer z hostem zgodnym z MCP, dodaj ten wpis do pliku konfiguracji MCP hosta, np. settings.json, i ustaw GOOGLE_APPLICATION_CREDENTIALS na plik JSON ADC (lub skonfiguruj domyślny ADC za pomocą gcloud auth application-default login). Jeśli uzyskujesz dostęp do kont za pomocą konta menedżera, możesz też ustawić GOOGLE_ADS_LOGIN_CUSTOMER_ID. Dokładną lokalizację i nazwę pliku tej konfiguracji znajdziesz w dokumentacji hosta.

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

Wdrażanie w Google Cloud

Zamiast hostować ten Serwer MCP lokalnie, możesz go hostować w Google Cloud Run lub w dowolnej innej infrastrukturze działającej w chmurze. Jest to przydatne, jeśli chcesz udostępniać serwer różnym agentom lub uruchamiać go jako usługę internetową.

Wymagania wstępne

  1. Projekt Google Cloud.

  2. Zainstalowane i uwierzytelnione narzędzie wiersza poleceń gcloud z skonfigurowanym aktywnym projektem: 

    gcloud config set project YOUR_PROJECT_ID

Tworzenie i przekazywanie obrazu Dockera

Za pomocą Cloud Build możesz utworzyć obraz i przenieść go do Artifact Registry bez konieczności instalowania Dockera lokalnie.

  1. Utwórz repozytorium w Artifact Registry:

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

  2. Otwórz katalog projektu:

    cd <full path>/google-ads-mcp

  3. Utwórz i prześlij obraz:

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

    Pamiętaj, że ten krok musisz wykonać za każdym razem, gdy chcesz zaktualizować wdrożony serwer do najnowszej wersji.

Wdróż w Google Cloud Run

Upewnij się, że masz ustawione wymagane zmienne środowiskowe:

  • GOOGLE_PROJECT_ID: identyfikator projektu Google Cloud, który ma odpowiednie poziomy dostępu do interfejsu API.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: identyfikator klienta OAuth 2.0 (skonfigurowany jako aplikacja internetowa w projekcie Google Cloud) na potrzeby uwierzytelniania OAuth na poziomie aplikacji. Upewnij się, że:
    • Masz dodane odpowiednie autoryzowane identyfikatory URI przekierowania dla wszystkich klientów AI, z którymi planujesz się połączyć (np. https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect lub https://antigravity.google/oauth-callback).
    • Masz dodany zakres https://www.googleapis.com/auth/adwords do ekranu zgody OAuth w sekcji Interfejsy API i usługi > Ekran zgody OAuth > Dostęp do danych (Dodaj lub usuń zakresy).
    • Jeśli stan publikowania ekranu zgody OAuth jest ustawiony na Testowanie (domyślnie), masz dodane konta Google łączące się z serwerem MCP jako Użytkownicy testowi w sekcji Interfejsy API i usługi > Ekran zgody OAuth > Odbiorcy (Użytkownicy testowi > + Dodaj użytkowników).
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: tajny klucz klienta OAuth odpowiadający identyfikatorowi klienta OAuth.
  • GOOGLE_ADS_MCP_BASE_URL: publiczny podstawowy adres URL, pod którym jest dostępny serwer MCP (np. https://google-ads-mcp-xyz-uc.a.run.app). Ponieważ Google Cloud Run generuje ten adres URL podczas wstępnego wdrożenia, najpierw wdróż bez tej zmiennej, a potem zaktualizuj usługę po wdrożeniu.
  • FASTMCP_HOST: ustaw tę wartość na 0.0.0.0, aby FastMCP akceptował połączenia ze wszystkich adresów IP.

Wdróż usługę w Google Cloud Run:

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"

Gdy Cloud Run zakończy wdrażanie, pobierz przypisany adres URL usługi i zaktualizuj usługę za pomocą zmiennej środowiskowej 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"

Model uwierzytelniania i zabezpieczeń

Wdrożenie z użyciem --allow-unauthenticated wyłącza sprawdzanie IAM na poziomie infrastruktury Cloud Run (roles/run.invoker), dzięki czemu zewnętrzni klienci AI mogą się łączyć bez tokenów konta usługi Google Cloud. Uwierzytelnianie jest delegowane do warstwy aplikacji:

  • Gdy podasz GOOGLE_ADS_MCP_OAUTH_CLIENT_ID i GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET, Serwer MCP wymusza Google OAuth 2.0 we wszystkich przychodzących żądaniach, odpowiadając na nieuwierzytelnione elementy wywołujące odpowiedzią HTTP 401. Wszystkie żądania narzędzi są wykonywane wyłącznie w ramach tożsamości OAuth uwierzytelnionego wywołującego.
  • Pominięcie --allow-unauthenticated wymusza IAM infrastruktury Cloud Run, co wymaga, aby wywołujący przekazywali tokeny tożsamości OIDC Google Cloud z każdym żądaniem. Ponieważ standardowi klienci AI (np. Claude i ChatGPT) uwierzytelniają się za pomocą OAuth użytkownika, a nie tokenów tożsamości Google Cloud IAM, bezpośrednie połączenia z tych platform wymagają --allow-unauthenticated z OAuth na poziomie aplikacji.

Konfigurowanie klienta MCP

Po wdrożeniu skonfiguruj klienta MCP za pomocą adresu URL Cloud Run. Ponieważ serwer wymaga uwierzytelniania OAuth 2.0, klient musi obsługiwać przepływ OAuth MCP lub dostarczać autoryzowany token okaziciela:

  • Klienci z obsługą OAuth: w przypadku klientów, którzy obsługują wykrywanie OAuth MCP (np. Antigravity), połączenie z punktem końcowym powoduje wyświetlenie prośby o uwierzytelnienie, aby zalogować się w Google i przyznać zakres https://www.googleapis.com/auth/adwords (w konsoli Google Cloud wyświetlany jako .../auth/adwords).
  • Platformy AI innych firm (Claude, ChatGPT): w ustawieniach integracji lub łącznika klienta dodaj łącznik niestandardowy wskazujący adres URL Cloud Run ze ścieżką /mcp (np. https://your-cloud-run-url.a.run.app/mcp), wybierz uwierzytelnianie OAuth 2.0 (za pomocą własnego identyfikatora klienta OAuth i tajnego klucza klienta) i upewnij się, że identyfikator URI wywołania zwrotnego klienta jest dodany do autoryzowanych identyfikatorów URI przekierowania klienta OAuth. (Uczestnicy pilotażowego programu hostowanego punktu końcowego, którzy znajdują się na liście dozwolonych, mogą też zapoznać się z przewodnikiem konfiguracji hostowanego MCP).
  • Klienci bez obsługi OAuth: klienci, którzy nie obsługują przepływów HTTP OAuth, otrzymają odpowiedź HTTP 401 Unauthorized. W przypadku tych narzędzi użyj lokalnej konfiguracji stdio zamiast tego.

Przykładowa konfiguracja klienta obsługującego OAuth (np. ~/.gemini/settings.json):

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

Główne możliwości (narzędzia)

Serwer udostępnia narzędzia przeznaczone do wykrywania kont i raportowania skuteczności:

  • list_accessible_customers: zwraca listę identyfikatorów klientów Google Ads i nazw kont dostępnych dla uwierzytelnionego użytkownika.
  • search: wykonuje żądania w języku zapytań Google Ads (GAQL), aby pobrać dane o skuteczności zasobów, budżetach i stanie.

  • get_resource_metadata: pobiera metadane dotyczące typu zasobu interfejsu Google Ads API, np. "campaign".

    Jest to przydatne, aby zrozumieć strukturę danych i jakie pola są dostępne do wysyłania zapytań.

Przykładowe prompty na początek

Zapytaj, co potrafi serwer:

What can the google-ads-mcp server do?

Zapytaj o klientów:

What customers do I have access to?

Zapytaj o kampanie:

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