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 ustandaryzowane połączenie z interfejsem Google Ads API. Umożliwia agentom AI pobieranie i analizowanie danych na koncie, tworzenie komponentów, przesyłanie filmów i zarządzanie etykietami za pomocą języka naturalnego.

Zasoby i pomoc społeczności

• Repozytorium GitHub: w repozytorium google-ads-mcp znajdziesz wersje demonstracyjne i przykłady, a także możesz zgłaszać błędy i proponować funkcje.

  Aby zgłosić błąd lub poprosić o dodanie funkcji, użyj karty Problemy.

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

Informacje techniczne

Integracja serwera MCP Google Ads eliminuje konieczność pisania niestandardowego kodu do uwierzytelniania interfejsu Google Ads API, pobierania zasobów, analizowania danych oraz obsługiwanych mutacji komponentów lub etykiet. Serwer udostępnia wywoływalne narzędzia i zasoby referencyjne (patrz Podstawowe funkcje), które LLM może sprawdzać i wywoływać.

Najważniejsze dane techniczne

• Protokół: MCP (Model Context Protocol)
• Tryb: odczyt i częściowa zmiana (tworzenie zasobów, przesyłanie filmów i zarządzanie etykietami z weryfikacją typu „proponuj i potwierdź” lub konfigurowalny tryb tylko do odczytu)
• Język: Python 3.10 lub nowszy
• Transport: standardowy strumień wejścia/wyjścia (stdio) lub strumieniowy protokół HTTP (streamable-http w Cloud Run)
• Uwierzytelnianie: domyślne uwierzytelnianie aplikacji (dane logowania użytkownika OAuth 2.0 lub konto usługi) w przypadku lokalnego stdio lub dane logowania aplikacji internetowej OAuth 2.0 w przypadku zdalnego protokołu HTTP

Jak działa pętla interakcji

1. Prośba: przesyłasz prompta, np. „Jaką skuteczność ma moja kampania w tym tygodniu?” lub „Utwórz komponent z objaśnieniem dotyczący naszej letniej wyprzedaży”.
2. Wykrywanie: LLM sprawdza dostępne narzędzia i zasoby, a następnie wybiera pasujące narzędzie google-ads-mcp.
3. Weryfikacja wykonania lub uruchomienia próbnego: narzędzia do odczytu wysyłają zapytania bezpośrednio do interfejsu Google Ads API. Narzędzia do mutacji są najpierw uruchamiane w trybie propozycji (validate_only=True), aby zweryfikować dane wejściowe bez wprowadzania zmian (patrz Proces bezpieczeństwa „proponuj i potwierdź”).
4. Wstrzykiwanie kontekstu: serwer MCP zwraca ustrukturyzowane wyniki zapytania lub proponowane wpisy change_items i podsumowanie weryfikacji checksum do okna kontekstu LLM.
5. Odpowiedź i potwierdzenie: LLM wyświetla odpowiedź lub prosi o potwierdzenie proponowanych zmian. Po zatwierdzeniu LLM ponownie wywołuje narzędzie do mutacji z parametrem validate_only=False i odpowiadającą mu wartością checksum, aby zatwierdzić zmianę.

Rozpocznij

Aby skonfigurować i uruchomić serwer MCP Google Ads lokalnie, wykonaj te czynności. Aby wdrożyć udostępnioną usługę zdalną, zapoznaj się z artykułem Wdrażanie w Google Cloud.

Wymagania wstępne

Zanim skonfigurujesz serwer, wykonaj te czynności w środowisku lokalnym i w konsoli Google Cloud:

• Projekt Google Cloud: utwórz lub wybierz projekt Google Cloud z włączonym interfejsem Google Ads API. Włączenie interfejsu API zapewnia dostęp testowy, który umożliwia testowanie przepływów pracy związanych z odczytem i modyfikacją na kontach testowych. Aby uzyskać dostęp do kont produkcyjnych, sprawdź na stronie Przegląd interfejsu Google Ads API, czy masz dostęp Explorer, podstawowy lub standardowy, albo poproś o jeden z tych poziomów dostępu. W przeciwnym razie wywołania produkcyjne zakończą się błędem AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION. 9 września 2026 r. Google wycofa tokeny programisty (GOOGLE_ADS_DEVELOPER_TOKEN). Poziom dostępu do interfejsu API zależy od projektu w chmurze Google Cloud, który jest właścicielem klienta OAuth lub konta usługi.
• Dane logowania: tryb lokalny stdio uwierzytelnia się za pomocą domyślnego uwierzytelniania aplikacji (ADC) z pliku JSON tajnego klucza klienta OAuth 2.0 lub konta usługi w projekcie w chmurze. W razie potrzeby ustaw zmienną środowiskową GOOGLE_CLOUD_PROJECT, aby określić domyślny projekt limitu lub ADC. Zdalne wdrożenia streamable-http wymagają identyfikatora klienta i tajnego klucza klienta aplikacji internetowej OAuth 2.0 (patrz Wdrażanie w Google Cloud Run).
• Oprogramowanie lokalne (w trybie stdio): zainstaluj Pythona w wersji 3.10 lub nowszej, pipx i narzędzie wiersza poleceń gcloud (używane do generowania plików ADC użytkownika).

Konfiguracja

1. Wygeneruj domyślne uwierzytelnianie aplikacji (ADC) za pomocą klienta OAuth z projektu Google Cloud z włączonym interfejsem API i uwzględnij zakres interfejsu Google Ads API:

   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
   

   Zastąp te elementy:

   • PATH_TO_CLIENT_SECRET_JSON: ścieżka do pliku JSON tajnego klucza klienta OAuth 2.0.

   To polecenie wyświetla Credentials saved to file: [PATH_TO_CREDENTIALS_JSON] (np. ~/.config/gcloud/application_default_credentials.json w systemach Linux i macOS). Aby uwierzytelnić się za pomocą konta usługi, pomiń ten krok i wskaż w GOOGLE_APPLICATION_CREDENTIALS plik JSON klucza konta usługi lub przekaż --impersonate-service-account do gcloud auth application-default login.

2. Dodaj serwer do pliku konfiguracji MCP hosta (np. ~/.gemini/config/mcp_config.json, ~/.gemini/settings.json lub ~/.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"
         }
       }
     }
   }
   

   Zastąp te elementy:

   • PROJECT_ID: identyfikator Twojego projektu Google Cloud;
   • PATH_TO_CREDENTIALS_JSON: ścieżka do pliku JSON domyślnych danych uwierzytelniających aplikacji wyświetlonego w kroku 1 lub do pliku JSON klucza konta usługi. Jeśli używasz domyślnej lokalizacji pliku ADC gcloud, możesz pominąć GOOGLE_APPLICATION_CREDENTIALS.

   Aby uzyskać dostęp do kont klientów przez konto menedżera, ustaw GOOGLE_ADS_LOGIN_CUSTOMER_ID (10 cyfr bez łączników) w env lub przekaż parametr login_customer_id w poszczególnych wywołaniach narzędzia.

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

Serwer MCP Google Ads zapewnia klientowi AI dostęp na żywo do danych raportowania konta oraz narzędzi do tworzenia komponentów, przesyłania filmów i zarządzania etykietami. Połącz serwer MCP z poniższymi narzędziami towarzyszącymi, aby pomóc agentowi w tworzeniu prawidłowych zapytań w języku Google Ads Query Language (GAQL) i diagnozowaniu zmian skuteczności konta. Narzędzia te generują też kod biblioteki klienta, np. skrypty do łączenia utworzonych komponentów z kampaniami lub wykonywania innych nieobsługiwanych mutacji:

• Umiejętności agenta interfejsu Google Ads API: przenośne moduły przepływu pracy (w tym google-ads-api-mcp-setup, google-ads-api-account-diagnostics i google-ads-api-quickstart), które pomagają agentowi korzystać z serwera MCP Google Ads przy mniejszym wykorzystaniu tokenów. Uruchom podane niżej polecenie, aby je zainstalować (wymaga to Node.js), lub zapoznaj się z przewodnikiem po umiejętnościach agenta interfejsu Google Ads API, aby dowiedzieć się, jak skonfigurować 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, weryfikację GAQL, generowanie kodu biblioteki klienta i rozwiązywanie problemów z konwersjami offline. Przeczytaj artykuł Czym jest asystent interfejsu Google Ads API Developer Assistant? lub postępuj zgodnie z przewodnikiem instalacji.

Najważniejsze funkcje

W sekcjach poniżej opisano narzędzia serwera do odczytu, narzędzia do częściowej mutacji i zasoby referencyjne. Od wersji v0.0.6 narzędzia są domyślnie rejestrowane z prefiksem przestrzeni nazw kategorii (np. search_search). Podczas uaktualniania promptów lub list dozwolonych z wersji bez prefiksu zaktualizuj nazwy narzędzi lub ustaw pusty prefiks ("") w tools_config.yaml (patrz Konfigurowanie przestrzeni nazw narzędzi i trybu tylko do odczytu).

Narzędzia do czytania

• customers_list_accessible_customers (narzędzie list_accessible_customers): zwraca identyfikatory klienta Google Ads, do których uwierzytelniony użytkownik ma bezpośredni dostęp.
• search_search (narzędzie search): tworzy i wykonuje zapytania GAQLSearchStream na podstawie uporządkowanych parametrów (customer_id, resource i fields oraz opcjonalnych parametrów conditions, orderings, limit i login_customer_id), a nie nieprzetworzonego ciągu GAQL. Każde zapytanie dołącza PARAMETERS omit_unselected_resource_names=true, aby pobrać atrybuty, dane, segmenty, budżety i stan zasobu.
• metadata_get_resource_metadata (narzędzie get_resource_metadata): pobiera atrybuty, dane i segmenty, które można wybierać, filtrować i sortować, dla typu zasobu interfejsu Google Ads API (np. "campaign"). Użyj tych metadanych, aby przed wywołaniem narzędzia search_search wykryć prawidłowe pola zapytania, w tym dane i segmenty dodane w mniejszych wersjach, takich jak v26.2.

Narzędzia do modyfikowania danych (częściowa obsługa)

• assets_create_asset (narzędzie create_asset): tworzy samodzielne komponenty Google Ads z oddzielnymi parametrami dla komponentów typu TEXT, IMAGE, YOUTUBE_VIDEO, SITELINK, CALLOUT i STRUCTURED_SNIPPET. Przekaż słownik extra_params dla innych zmiennych typów AssetService (takich jak PRICE, PROMOTION, CALL lub BUSINESS_MESSAGE) i uwzględnij final_urls na poziomie głównym obok sitelink_link_text dla zasobów SITELINK. Ścieżki plików lokalnych (image_asset_path) działają tylko w trybie lokalnym stdio. W przypadku zdalnych wdrożeń HTTP przekaż parametr image_asset_data zakodowany w formacie base64 z parametrem image_asset_mime_type ustawionym na IMAGE_PNG, IMAGE_JPEG lub IMAGE_GIF (do 20 MB).
• assets_upload_video_asset (narzędzie upload_video_asset): przesyła lokalny plik wideo (.3gp, .avi, .flv, .mkv, .mov, .mp4, .mpeg, .mpg, .ogg, .webm lub .wmv) do YouTube za pomocą interfejsu Google Ads API tylko w trybie lokalnym stdio. Parametry video_title i video_description są wymagane, a domyślne ustawienie prywatności to UNLISTED (lub PUBLIC na kanałach firmowych należących do reklamodawcy z protokołem OAuth użytkownika). To narzędzie zwraca wartość video_upload_id (i nazwę zasobu) Google Ads, a nie 11-znakowy identyfikator video_id YouTube. Wysyłaj zapytania do you_tube_video_upload za pomocą narzędzia search_search (filtrując według you_tube_video_upload.video_upload_id) do you_tube_video_upload.state = 'PROCESSED'. Następnie przekaż you_tube_video_upload.video_id jako parametr youtube_video_id do assets_create_asset (asset_type="YOUTUBE_VIDEO").
• labels_manage_labels (narzędzie manage_labels): tworzy, aktualizuje i usuwa etykiety kont, w tym nazwę, opis i szesnastkowy kolor tła.
• labels_manage_label_associations (narzędzie manage_label_associations): obsługuje operacje powiązania etykiet CREATE i REMOVE (UPDATE nie jest obsługiwane) w zasobach CAMPAIGN, CUSTOMER, AD_GROUP i AD_GROUP_CRITERION. W przypadku zasobów CUSTOMER parametr resource_id jest opcjonalny i domyślnie ma wartość customer_id. Przekaż złożony identyfikator {ad_group_id}~{criterion_id} zasobów AD_GROUP_CRITERION i usuń powiązania, przekazując resource_id i label_id lub association_resource_name. Etykiety AD_GROUP_AD na poziomie reklamy nie są obsługiwane.

Zasoby referencyjne

Serwer udostępnia 4 zasoby MCP tylko do odczytu, które pozostają podłączone niezależnie od ustawień tools_config.yaml:

• resource://discovery-document: przegląd zasobów, metod usług i schematów interfejsu Google Ads API w formacie JSON REST. Uzupełnia narzędzie metadata_get_resource_metadata, które zwraca pola zapytania GAQL, które można wybierać, filtrować i sortować.
• resource://metrics: dokumentacja referencyjna HTML dotycząca danych interfejsu Google Ads API.
• resource://segments: dokumentacja referencyjna HTML dotycząca segmentów interfejsu Google Ads API.
• resource://release-notes: informacje o wersji interfejsu Google Ads API w formacie HTML, które zawierają zmiany w wersjach i nowe funkcje.

Przepływ pracy dotyczący bezpieczeństwa oparty na propozycji i potwierdzeniu

Każde narzędzie do modyfikacji (assets_create_asset, assets_upload_video_asset, labels_manage_labels i labels_manage_label_associations) wymusza dwuetapowy proces proponowania i potwierdzania, aby zapobiec niezamierzonym zmianom na koncie:

1. Proponowanie (validate_only=True, domyślne): sprawdza dane wejściowe bez zatwierdzania zmian. Narzędzia do obsługi komponentów i etykiet wykonują uruchomienie próbne interfejsu Google Ads API validate_only. Ponieważ YouTubeVideoUploadService nie ma trybu próbnego, assets_upload_video_asset sprawdza poprawność pliku lokalnego i wiąże jego rozmiar oraz sygnaturę czasową modyfikacji. Każde narzędzie zwraca zrozumiałe dla człowieka wpisy change_items i bezstanowy skrót SHA-256 checksum powiązany z parametrem customer_id i ładunkiem żądania.
2. Potwierdzenie (validate_only=False): po przedstawieniu listy change_items i otrzymaniu Twojej zgody agent ponownie wywołuje narzędzie z validate_only=False, identycznym parametrem i argumentami customer_id oraz wartością checksum z kroku 1. Przed wprowadzeniem zmian na koncie serwer odrzuca brakujące lub niezgodne sumy kontrolne.

Konfigurowanie przestrzeni nazw narzędzi i trybu tylko do odczytu

Serwer zawiera domyślny plik tools_config.yaml ze wszystkimi 5 włączonymi kategoriami narzędzi (customers, search, metadata, labels i assets). Dostosuj tools_config.yaml, aby selektywnie włączać lub wyłączać poszczególne narzędzia lub przestrzenie nazw, zmieniać lub usuwać prefiksy przestrzeni nazw albo wymuszać wdrożenie wyłącznie do odczytu.

Podczas uruchamiania serwer rozpoznaje tools_config.yaml w następującej kolejności:

1. jawna ścieżka w zmiennej środowiskowej GOOGLE_ADS_MCP_TOOLS_CONFIG (zalecane w przypadku lokalnych hostów stdio, których katalog roboczy może się różnić od folderu projektu).
2. Plik tools_config.yaml w bieżącym katalogu roboczym serwera.
3. Domyślny plik tools_config.yaml dołączony do pakietu.

Jeśli GOOGLE_ADS_MCP_TOOLS_CONFIG wskazuje brakujący plik lub jeśli którykolwiek z rozwiązanych plików konfiguracji jest nieprawidłowy, serwer zgłasza błąd podczas uruchamiania, zamiast przywracać ustawienia domyślne.

Ten minimalny plik tools_config.yaml wymusza wdrożenie tylko do odczytu:

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

Ten plik tools_config.yaml dostosowuje prefiksy i filtruje poszczególne narzędzia (np. udostępnia narzędzie base64 create_asset w Cloud Run, wyłączając jednocześnie narzędzie upload_video_asset, które działa tylko lokalnie):

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

Przykładowe prompty na początek

Po połączeniu się z serwerem wypróbuj te prompty w kliencie MCP.

Pytanie o możliwości serwera

What can the google-ads-mcp server do?

Pytanie o klientów

What customers do I have access to?

Pytanie 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

Tworzenie zasobów, przesyłanie filmów i zarządzanie etykietami

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

Wdrożenie w Google Cloud

Aby udostępnić serwer MCP wielu agentom lub uruchomić go jako usługę internetową, hostuj go w Google Cloud Run lub u innego dostawcy infrastruktury w chmurze, zamiast uruchamiać go lokalnie.

Wymagania wstępne

1. projekt Google Cloud z włączonym interfejsem Google Ads API (wymagania dotyczące dostępu do wersji produkcyjnej znajdziesz w sekcji Wymagania wstępne);

2. Zainstalowane i uwierzytelnione narzędzie wiersza poleceń gcloud, które jest skonfigurowane z aktywnym projektem:

   gcloud config set project PROJECT_ID
   

   Zastąp te elementy:

   • PROJECT_ID: identyfikator Twojego projektu Google Cloud;

Tworzenie i przekazywanie obrazu Dockera

Użyj Cloud Build, aby utworzyć obraz kontenera i przesłać go do Artifact Registry bez lokalnego instalowania Dockera:

1. Utwórz repozytorium w Artifact Registry:

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

2. Utwórz i prześlij obraz z tagu wersji w repozytorium GitHub (lub z . w lokalnym procesie płatności, jeśli dostosowano Dockerfile lub tools_config.yaml):

   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
   

   Zastąp te elementy:

   • PROJECT_ID: identyfikator Twojego projektu Google Cloud;

   Za każdym razem, gdy aktualizujesz google-ads-mcp lub uaktualniasz dołączoną bibliotekę klienta google-ads w języku Python do nowych wersji interfejsu Google Ads API (np. v26.2), musisz ponownie utworzyć i wdrożyć obraz.

Wdróż w Google Cloud Run

Skonfiguruj te zmienne środowiskowe i obiekty tajne dla usługi Cloud Run:

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: identyfikator klienta aplikacji internetowej OAuth 2.0 z projektu Google Cloud z włączonym interfejsem API na potrzeby uwierzytelniania OAuth na poziomie aplikacji. Wykonaj te czynności, aby skonfigurować protokół OAuth:
  • Dodaj autoryzowane identyfikatory URI przekierowania dla wszystkich klientów AI, których chcesz połączyć (np. https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect lub https://antigravity.google/oauth-callback).
  • Dodaj 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 publikacji ekranu zgody OAuth jest ustawiony na Testowanie (domyślnie), dodaj 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 serwera MCP (np. https://google-ads-mcp-xyz-uc.a.run.app). Cloud Run przypisuje ten adres URL podczas początkowego wdrażania, więc najpierw przeprowadź wdrożenie bez tej zmiennej, a potem zaktualizuj usługę.
• GOOGLE_ADS_MCP_JWT_SIGNING_KEY (zalecane w przypadku Cloud Run z wieloma instancjami): trwały obiekt tajny, który podpisuje tokeny JWT FastMCP podczas ponownego uruchamiania kontenerów i skalowania poziomego.
• GOOGLE_ADS_MCP_STORAGE_TYPE (zalecane w przypadku Cloud Run z wieloma instancjami): trwały backend do rejestracji i tokenów klienta OAuth (redis z GOOGLE_ADS_MCP_STORAGE_REDIS_URL lub firestore). Ponieważ standardowy v0.0.6 Dockerfile instaluje tylko backend w pamięci, najpierw zainstaluj py-key-value-aio[redis] lub .[firestore] w niestandardowym Dockerfile. Korzystanie z firestore wymaga też bazy danych Firestore i roli uprawnień roles/datastore.user na koncie usługi Cloud Run. W przypadku testowania pojedynczej instancji z pamięcią masową w pamięci przekaż --max-instances=1.
• GOOGLE_ADS_LOGIN_CUSTOMER_ID (opcjonalnie): domyślny 10-cyfrowy identyfikator klienta konta menedżera (bez łączników) używany, gdy wywołania narzędzia pomijają parametr login_customer_id.
• GOOGLE_ADS_MCP_TOOLS_CONFIG (opcjonalnie): ścieżka kontenera do niestandardowego pliku tools_config.yaml (np. zamontowanego z Secret Managera w /etc/mcp/tools_config.yaml, aby wymusić tryb tylko do odczytu bez ponownego tworzenia obrazu). Zobacz Konfigurowanie przestrzeni nazw narzędzi i trybu tylko do odczytu.

Przechowaj GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET i GOOGLE_ADS_MCP_JWT_SIGNING_KEY w Secret Managerze i wdróż usługę w Google Cloud Run:

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"

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

Zastąp te elementy:

• PROJECT_ID: identyfikator Twojego projektu Google Cloud;
• CLIENT_ID: identyfikator klienta aplikacji internetowej OAuth 2.0.
• MCP_OAUTH_CLIENT_SECRET: nazwa obiektu tajnego w usłudze Secret Manager, w którym przechowywany jest tajny klucz klienta OAuth 2.0.
• MCP_JWT_SIGNING_KEY: nazwa obiektu tajnego w Secret Managerze, w którym przechowywany jest klucz podpisywania JWT.
• CLOUD_RUN_SERVICE_URL: nazwa hosta przypisana do usługi Cloud Run (np. google-ads-mcp-xyz-uc.a.run.app).

Model uwierzytelniania i zabezpieczeń

Wdrożenie za pomocą --allow-unauthenticated wyłącza sprawdzanie uprawnień infrastruktury Cloud Run (roles/run.invoker), dzięki czemu zewnętrzne klienty AI mogą łączyć się bez tokenów kont usługi Google Cloud. Uwierzytelnianie jest przekazywane do warstwy aplikacji:

• Gdy ustawione są parametry GOOGLE_ADS_MCP_OAUTH_CLIENT_ID i GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET, serwer wymusza Google OAuth 2.0 przy każdym żądaniu i zwraca kod stanu HTTP 401 Unauthorized nieuwierzytelnionym rozmówcom. Każde wywołanie narzędzia jest wykonywane w ramach uwierzytelnionej tożsamości OAuth elementu wywołującego.
• Pominięcie --allow-unauthenticated 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) używają protokołu OAuth użytkownika, a nie tokenów Google Cloud IAM, więc połączenia bezpośrednie wymagają --allow-unauthenticated połączonego z protokołem OAuth na poziomie aplikacji.

Konfigurowanie klienta MCP

Po wdrożeniu skonfiguruj klienta MCP za pomocą adresu URL usługi Cloud Run. Ponieważ serwer wymusza protokół OAuth 2.0, klient musi obsługiwać przepływ OAuth MCP lub podać autoryzowany token okaziciela:

• Klienty z obsługą protokołu OAuth: w klientach, które obsługują wykrywanie protokołu OAuth MCP (takich jak Antigravity), połączenie powoduje wyświetlenie potwierdzenia od Google w celu przyznania zakresu https://www.googleapis.com/auth/adwords (wyświetlanego jako .../auth/adwords w konsoli Google Cloud).
• Platformy AI innych firm (Claude, ChatGPT): w ustawieniach oprogramowania sprzęgającego klienta dodaj niestandardowe oprogramowanie sprzęgające wskazujące adres URL usługi ze ścieżką /mcp (np. https://google-ads-mcp-xyz-uc.a.run.app/mcp). Wybierz uwierzytelnianie OAuth 2.0 za pomocą identyfikatora klienta OAuth i tajnego klucza klienta, a następnie potwierdź, że identyfikator URI wywołania zwrotnego klienta znajduje się w autoryzowanych identyfikatorach URI przekierowania klienta OAuth.
• Klienty bez obsługi protokołu OAuth: klienty, które nie obsługują przepływów HTTP OAuth, otrzymują kod stanu HTTP 401 Unauthorized. W przypadku tych klientów użyj lokalnej konfiguracji stdio.

W tym przykładzie skonfigurowano narzędzie wiersza poleceń gemini w ~/.gemini/settings.json (w przypadku Google Antigravity w ~/.gemini/config/mcp_config.json zastąp "httpUrl" wartością "serverUrl" lub "url"):

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

Zastąp te elementy:

• CLOUD_RUN_SERVICE_URL: nazwa hosta przypisana do usługi Cloud Run (np. google-ads-mcp-xyz-uc.a.run.app).

Dalsze kroki

• Instalowanie umiejętności agenta interfejsu Google Ads API
• Więcej informacji o asystencie dla deweloperów korzystających z interfejsu Google Ads API
• Instalowanie i używanie asystenta dewelopera interfejsu Google Ads API