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 pomost do interfejsu Google Ads API, który umożliwia agentom AI analizowanie i pobieranie danych o kampaniach za pomocą języka naturalnego.

Materiały i pomoc dla społeczności

Omówienie techniczne

Wdrażając ten serwer MCP, nie musisz pisać niestandardowego „kodu łączącego” do uwierzytelniania w interfejsie Google Ads API, pobierania zasobów i parsowania danych. Serwer udostępnia konkretne narzędzia, które model LLM może samodzielnie wykrywać i wywoływać.

Najważniejsze specyfikacje

  • Protokół: MCP (Model Context Protocol)
  • Tryb: Tylko do odczytu (bieżąca wersja)
  • Język: Python
  • Transport: standardowe wejście/wyjście (stdio)
  • Uwierzytelnianie: OAuth 2.0 lub konto usługi

Jak działa pętla interakcji

  1. Żądanie: użytkownik przesyła zapytanie, np. „Jakie są wyniki mojej kampanii w tym tygodniu?”.
  2. Odkrywanie: LLM sprawdza dostępne narzędzia i identyfikuje funkcje wyszukiwania.google-ads-mcp
  3. Wykonanie: serwer MCP wykonuje podstawową logikę Pythona, aby wysyłać zapytania 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ć i używać serwera MCP Google Ads, 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. Dokładną lokalizację i nazwę pliku konfiguracji znajdziesz w dokumentacji hosta.

JSON

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

Wdrożenie w Google Cloud

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

Wymagania wstępne

  1. Projekt Google Cloud.

  2. Narzędzie wiersza poleceń gcloud musi być zainstalowane, uwierzytelnione i musi mieć skonfigurowany aktywny projekt:

    gcloud config set project YOUR_PROJECT_ID

Tworzenie i przekazywanie obrazu Dockera

Możesz użyć Cloud Build do utworzenia obrazu i przesłania 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.

Wdrażanie 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, którego ma używać serwer MCP.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: tajny klucz klienta OAuth, którego ma używać serwer MCP.
  • GOOGLE_ADS_MCP_BASE_URL: podstawowy adres URL, pod którym dostępny jest serwer MCP: zostanie on automatycznie przypisany przez Google Cloud Run po pierwszym wdrożeniu. Zmienne środowiskowe możesz zaktualizować po wdrożeniu.
  • FASTMCP_HOST: ustaw wartość 0.0.0.0, aby umożliwić FastMCP akceptowanie połączeń ze wszystkich adresów IP.
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,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0"

Konfigurowanie klienta MCP

Po wdrożeniu zaktualizuj konfigurację klienta MCP (np.~/.gemini/settings.json), aby używać adresu URL Cloud Run.

{
  "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 języka zapytań Google Ads (GAQL), aby pobierać dane o zasobach, budżetach i stanie.

  • get_resource_metadata: pobiera metadane dotyczące typu zasobu interfejsu Google Ads API, np. „kampania”.

    Jest to przydatne, aby poznać strukturę danych i pola 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