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) bezpieczną interakcję z zewnętrznymi danymi i aplikacjami. Serwer MCP Google Ads zapewnia ustandaryzowany most do interfejsu Google Ads API, który umożliwia agentom AI analizowanie i pobieranie danych kampanii za pomocą języka naturalnego.

Zasoby i pomoc społeczności

Informacje techniczne

Dzięki wdrożeniu tego serwera MCP nie musisz pisać niestandardowego „kodu łączącego” na potrzeby uwierzytelniania interfejsu Google Ads API, pobierania zasobów i analizowania danych. Serwer udostępnia określone narzędzia, które LLM może samodzielnie wykrywać i wywoływać.

Najważniejsze dane techniczne

  • Protokół: MCP (Model Context Protocol)
  • Tryb: tylko do odczytu (bieżąca wersja)
  • Język: Python
  • Transport: standardowy strumień wejścia/wyjścia (stdio) lub strumieniowy protokół HTTP (streamable-http / Cloud Run)
  • Uwierzytelnianie: OAuth 2.0 lub konto usługi

Jak działa pętla interakcji

  1. Prośba: użytkownik przesyła zapytanie, np. „Jakie są wyniki mojej kampanii w tym tygodniu?”.
  2. Odkrywanie: 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. Wstrzykiwanie kontekstu: ustrukturyzowane wyniki są zwracane do okna kontekstu LLM.
  5. Odpowiedź: LLM syntetyzuje dane w odpowiedź zrozumiałą dla człowieka.

Rozpocznij

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

Wymagania wstępne

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

Konfiguracja

Aby zintegrować serwer z hostem zgodnym z MCP, dodaj ten wpis do pliku konfiguracji MCP hosta, np. settings.json, i wskaż GOOGLE_APPLICATION_CREDENTIALS w pliku JSON ADC (lub skonfiguruj domyślne 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"
      }
    }
  }
}

Opcjonalnie: wyposaż agenta w umiejętności i asystenta programisty

Serwer MCP Google Ads zapewnia klientowi AI dostęp tylko do odczytu do danych na aktywnym koncie. Aby pomóc agentowi tworzyć prawidłowe zapytania w języku zapytań Google Ads (GAQL), diagnozować zmiany skuteczności konta i generować kod biblioteki klienta, sparuj serwer MCP z tymi narzędziami towarzyszącymi:

  • Umiejętności agenta interfejsu Google Ads API: przenośne moduły instrukcji i procesów związanych z interfejsem Google Ads API, w tym google-ads-api-mcp-setup, google-ads-api-account-diagnostics i google-ads-api-quickstart, które uczą agenta, jak skutecznie korzystać z serwera MCP Google Ads przy mniejszym wykorzystaniu tokenów. Zainstaluj je za pomocą jednego polecenia (wymaga Node.js) lub zapoznaj się z przewodnikiem po umiejętnościach agenta interfejsu Google Ads API, aby poznać opcje Antigravity, Claude Code, Codex i Cursor:

    npx skills add google/skills/skills/ads

  • Asystent programisty interfejsu Google Ads API: modułowa wtyczka do Google Antigravity i Claude Code, która umożliwia lokalną kontrolę schematu Protobuf, automatyczną weryfikację GAQL, generowanie kodu biblioteki klienta (w tym skryptów mutacji) i rozwiązywanie problemów z konwersjami offline. Dowiedz się, jak działa, w artykule Co to jest asystent Google Ads API Developer Assistant? lub postępuj zgodnie z instrukcją instalacji.

Wdrożenie 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ępnić serwer różnym agentom lub uruchomić go jako usługę internetową.

Wymagania wstępne

  1. projekt Google Cloud,

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

    gcloud config set project YOUR_PROJECT_ID

Tworzenie i przekazywanie obrazu Dockera

Możesz użyć Cloud Build, aby utworzyć obraz i przenieść go do Artifact Registry bez konieczności lokalnego instalowania Dockera.

  1. Utwórz repozytorium w Artifact Registry:

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

  2. Przejdź do katalogu 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

Ustaw wymagane zmienne środowiskowe:

  • GOOGLE_PROJECT_ID: identyfikator Twojego 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:
    • Dodano odpowiednie autoryzowane identyfikatory URI przekierowania dla wszystkich klientów AI, których planujesz połączyć (takich jak https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect lub https://antigravity.google/oauth-callback).
    • Zakres https://www.googleapis.com/auth/adwords został dodany 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 publikacji ekranu zgody OAuth jest ustawiony na Testowanie (domyślnie), konta Google łączące się z serwerem MCP zostały dodane 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 dostępny jest serwer MCP (np. https://google-ads-mcp-xyz-uc.a.run.app). Google Cloud Run generuje ten adres URL podczas początkowego wdrażania, dlatego najpierw przeprowadź wdrożenie bez tej zmiennej, a po wdrożeniu zaktualizuj usługę.
  • FASTMCP_HOST: ustaw wartość 0.0.0.0, aby umożliwić FastMCP akceptowanie połączeń 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 uprawnień na poziomie infrastruktury Cloud Run (roles/run.invoker), dzięki czemu zewnętrzne klienty AI mogą się łączyć bez konieczności używania tokenów konta usługi Google Cloud. Uwierzytelnianie jest przekazywane do warstwy aplikacji:

  • Gdy podane są parametry GOOGLE_ADS_MCP_OAUTH_CLIENT_ID i GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET, serwer MCP wymusza stosowanie Google OAuth 2.0 we wszystkich żądaniach przychodzących, odrzucając nieuwierzytelnione wywołania z odpowiedzią HTTP 401. Wszystkie żądania narzędzi są wykonywane ściśle w ramach tożsamości OAuth uwierzytelnionego elementu wywołującego.
  • Pominięcie --allow-unauthenticated wymusza uprawnienia infrastruktury Cloud Run, co wymaga od wywołujących przekazywania tokenów tożsamości OIDC Google Cloud przy każdym żądaniu. Standardowi klienci AI (tacy jak Claude i ChatGPT) uwierzytelniają się za pomocą protokołu OAuth użytkownika, a nie tokenów tożsamości Google Cloud IAM, dlatego bezpośrednie połączenia z tych platform wymagają --allow-unauthenticated z protokołem OAuth na poziomie aplikacji.

Konfigurowanie klienta MCP

Po wdrożeniu skonfiguruj klienta MCP za pomocą adresu URL Cloud Run. Serwer wymaga uwierzytelniania OAuth 2.0, dlatego klient musi obsługiwać proces MCP OAuth lub podać autoryzowany token okaziciela:

  • Klienty z obsługą protokołu OAuth: w przypadku klientów, którzy obsługują wykrywanie protokołu OAuth MCP (takich jak Antigravity), połączenie z punktem końcowym powoduje wyświetlenie monitu uwierzytelniania, który umożliwia zalogowanie się przez Google i przyznanie zakresu https://www.googleapis.com/auth/adwords (na konsoli Google Cloud widocznego jako .../auth/adwords).
  • Platformy AI innych firm (Claude, ChatGPT): w ustawieniach oprogramowania sprzęgającego lub integracji klienta dodaj oprogramowanie sprzęgające niestandardowe wskazujące adres URL Cloud Run ze ścieżką /mcp (np. https://your-cloud-run-url.a.run.app/mcp), wybierz uwierzytelnianie OAuth 2.0 (używając własnego identyfikatora klienta OAuth i tajnego klucza klienta) i upewnij się, że identyfikator URI wywołania zwrotnego klienta został dodany do autoryzowanych adresów URI przekierowania klienta OAuth. (Uczestnicy programu pilotażowego hostowanego punktu końcowego, którzy znajdują się na liście dozwolonych, mogą też zapoznać się z przewodnikiem po konfiguracji hostowanego protokołu MCP).
  • Klienty bez obsługi protokołu OAuth: klienty, które nie obsługują przepływów HTTP OAuth, otrzymają odpowiedź HTTP 401 Unauthorized. W przypadku tych narzędzi użyj lokalnej konfiguracji stdio.

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

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

Podstawowe funkcje (narzędzia)

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

  • list_accessible_customers: zwraca listę identyfikatorów klienta Google Ads i nazw kont dostępnych dla uwierzytelnionego użytkownika.
  • search: wykonuje żądania GAQL, aby pobrać dane o zasobach, budżety i stan.

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

    Jest to przydatne do zrozumienia struktury danych i tego, jakie pola są dostępne do wysyłania zapytań.

Przykładowe prompty na początek

Zapytaj, co może zrobić serwer:

What can the google-ads-mcp server do?

Zapytaj o klientów:

What customers do I have access to?

Zadawanie pytań 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

Dalsze kroki