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 danymi i aplikacjami zewnętrznymi. Serwer MCP Google Ads 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

Omówienie 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 określone narzędzia , które LLM może wykrywać i wywoływać autonomicznie.

Najważniejsze cechy

  • 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. "Jaka jest skuteczność mojej kampanii w tym tygodniu?".
  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 czytelną dla człowieka odpowiedź.

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 uwierzytelniające z konsoli dewelopera Google Ads:

  • Token programisty: unikalny ciąg dostępu składający się z 22 znaków.
  • Identyfikator projektu: identyfikator Twojego projektu Google Cloud.
  • Dane uwierzytelniające OAuth: para identyfikator klienta OAuth 2.0 i tajny klucz klienta lub zestaw domyślnych danych uwierzytelniających aplikacji.

Konfiguracja

Aby zintegrować serwer z hostem zgodnym z MCP, dodaj ten wpis do pliku konfiguracyjnego MCP hosta, np. settings.json. Dokładną lokalizację i nazwę pliku konfiguracyjnego 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",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
      }
    }
  }
}

Wdrażanie w Google Cloud

Zamiast hostować ten serwer MCP lokalnie, możesz go hostować 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ę sieciową.

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 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. 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 Twojego projektu Google Cloud.
  • GOOGLE_ADS_DEVELOPER_TOKEN: token programisty, którego ma używać serwer MCP.
  • 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 jest dostępny serwer MCP. Zostanie on automatycznie przypisany przez Google Cloud Run po pierwszym wdrożeniu. Po wdrożeniu możesz zaktualizować zmienne środowiskowe.
  • FASTMCP_HOST: ustaw tę wartość na 0.0.0.0, aby FastMCP akceptował połączenia 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_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,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"
    }
  }
}

Najważniejsze funkcje (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. „kampania”.

    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