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 od społeczności

Informacje ogólne związane z technologią

Wdrażając ten serwer MCP, nie musisz pisać niestandardowego „kodu łączącego” do uwierzytelniania interfejsu 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 (obecna wersja)
  • Język: Python
  • Transport: standardowe wejście/wyjście (stdio) lub HTTP/SSE (Cloud Run)
  • 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

Zanim rozpoczniesz 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 konfiguracyjnego MCP hosta, np. settings.json, i skieruj GOOGLE_APPLICATION_CREDENTIALS do pliku 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"
      }
    }
  }
}

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 zainstalowane, uwierzytelnione i skonfigurowane z aktywnym projektem:

    gcloud config set project YOUR_PROJECT_ID

Tworzenie i przekazywanie obrazu Dockera

Możesz użyć Cloud Build, aby utworzyć obraz i przesłać 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. 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.

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; jest on automatycznie przypisywany przez Google Cloud Run po pierwszym wdrożeniu. Zmienne środowiskowe możesz zaktualizować po wdrożeniu.
  • FASTMCP_HOST: ustaw tę wartość na 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 stanach.

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

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

Zadaj 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