Google Ads MCP sunucusu: Geliştirici entegrasyon kılavuzu

Model Context Protocol (MCP), büyük dil modellerinin (LLM'ler) harici veriler ve uygulamalarla güvenli bir şekilde etkileşim kurmasını sağlayan açık bir standarttır. Google Ads MCP sunucusu, Google Ads API'ye standart bir köprü sağlayarak yapay zeka ajanlarının doğal dil kullanarak kampanya verilerini analiz etmesine ve almasına olanak tanır.

Topluluk kaynakları ve destek

Teknik genel bakış

Bu MCP sunucusunu uygulayarak Google Ads API kimlik doğrulaması, kaynak getirme ve veri ayrıştırma için özel "yapıştırıcı kod" yazma ihtiyacını ortadan kaldırırsınız. Sunucu, LLM'nin bağımsız olarak keşfedip çağırabileceği belirli araçları kullanıma sunar.

Temel özellikler

  • Protokol: MCP (Model Bağlam Protokolü)
  • Mod: Salt okunur (mevcut sürüm)
  • Dil: Python
  • Taşıma: Standart giriş/çıkış (stdio) veya akış özellikli HTTP (streamable-http / Cloud Run)
  • Kimlik doğrulama: OAuth 2.0 veya hizmet hesabı

Etkileşim döngüsünün işleyiş şekli

  1. İstek: Kullanıcı, "Kampanyamın bu haftaki performansı nasıl?" gibi bir sorgu gönderir.
  2. Keşif: LLM, mevcut araçlarını inceler ve arama özelliklerini belirler. google-ads-mcp
  3. Yürütme: MCP sunucusu, Google Ads API'yi sorgulamak için temel Python mantığını yürütür.
  4. Bağlam ekleme: Yapılandırılmış sonuçlar, LLM'nin bağlam penceresine döndürülür.
  5. Yanıt: LLM, verileri insanların okuyabileceği bir yanıt haline getirir.

Başlayın

Google Ads MCP sunucusunu yapılandırmak ve kullanmak için aşağıdaki adımları uygulayın.

Ön koşullar

Yapılandırmadan önce Google Cloud Console'dan aşağıdaki kimlik bilgilerini aldığınızdan emin olun:

Yapılandırma

Sunucuyu MCP uyumlu bir ana makineye entegre etmek için ana makinenizin MCP yapılandırma dosyasına (ör. settings.json) aşağıdaki girişi ekleyin ve GOOGLE_APPLICATION_CREDENTIALS değerini ADC JSON dosyanıza yönlendirin (veya varsayılan ADC'yi gcloud auth application-default login ile yapılandırın). Hesaplara bir yönetici hesabı üzerinden erişiyorsanız GOOGLE_ADS_LOGIN_CUSTOMER_ID değerini de ayarlayabilirsiniz. Bu yapılandırmanın tam konumu ve dosya adı için barındırıcınızın dokümanlarına bakın.

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

İsteğe bağlı: Temsilcinizi beceriler ve Geliştirici Asistanı ile donatma

Google Ads MCP sunucusu, yapay zeka istemcinize canlı hesap verilerine salt okuma erişimi verir. Temsilcinizin geçerli Google Ads Sorgu Dili (GAQL) sorguları oluşturmasına, hesap performansı değişikliklerini teşhis etmesine ve istemci kitaplığı kodu oluşturmasına yardımcı olmak için MCP sunucusunu şu tamamlayıcı araçlarla eşleştirin:

  • Google Ads API temsilci becerileri: Temsilcinize Google Ads MCP sunucusunu daha düşük jeton ek yüküyle etkili bir şekilde nasıl kullanacağını öğreten, google-ads-api-mcp-setup, google-ads-api-account-diagnostics ve google-ads-api-quickstart dahil olmak üzere Google Ads API'ye özgü talimatların ve iş akışlarının taşınabilir modülleri. Bunları tek bir komutla yükleyin (Node.js gerekir) veya Antigravity, Claude Code, Codex ve Cursor seçenekleri için Google Ads API temsilci becerileri kılavuzuna bakın:

    npx skills add google/skills/skills/ads

  • Google Ads API Developer Assistant: Google Antigravity ve Claude Code için yerel Protobuf şeması incelemesi, programatik GAQL doğrulaması, istemci kitaplığı kod oluşturma (mutasyon komut dosyaları dahil) ve çevrimdışı dönüşüm sorunlarını giderme özellikleri sunan modüler bir eklentidir. Google Ads API Developer Assistant nedir? başlıklı makaleden nasıl çalıştığını öğrenebilir veya kurulum kılavuzundaki adımları uygulayabilirsiniz.

Google Cloud'da dağıtım

Bu MCP sunucusunu yerel olarak barındırmak yerine Google Cloud Run'da veya başka bir bulut tabanlı altyapıda barındırabilirsiniz. Sunucuyu farklı temsilciler arasında paylaşmak veya web hizmeti olarak çalıştırmak istiyorsanız bu seçenekten yararlanabilirsiniz.

Ön koşullar

  1. Google Cloud projesi

  2. gcloud komut satırı aracı yüklü, kimliği doğrulanmış ve etkin bir proje yapılandırılmış olmalıdır:

    gcloud config set project YOUR_PROJECT_ID

Docker görüntüsü oluşturma ve aktarma

Docker'ı yerel olarak yüklemenize gerek kalmadan görüntüyü derleyip Artifact Registry'ye aktarmak için Cloud Build'i kullanabilirsiniz.

  1. Artifact Registry'de bir depo oluşturun:

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

  2. Proje dizinine gidin:

    cd <full path>/google-ads-mcp

  3. Görüntüyü oluşturun ve gönderin:

    gcloud builds submit \
  --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .

    Dağıtılan sunucuyu en yeni sürüme güncellemek istediğinizde bu adımı uygulamanız gerektiğini unutmayın.

Google Cloud Run'a dağıtma

Gerekli ortam değişkenlerini ayarladığınızdan emin olun:

  • GOOGLE_PROJECT_ID: Uygun API erişim düzeylerine sahip Google Cloud proje kimliğiniz.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Uygulama düzeyinde OAuth kimlik doğrulaması için OAuth 2.0 istemci kimliği (Google Cloud projenizde web uygulaması olarak yapılandırılır). Şu noktalardan emin olun:
    • Bağlamayı planladığınız tüm yapay zeka istemcileri (ör. https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect veya https://antigravity.google/oauth-callback) için uygun yetkilendirilmiş yönlendirme URI'lerini eklediniz.
    • https://www.googleapis.com/auth/adwords kapsamını API'ler ve Hizmetler > OAuth kullanıcı rızası ekranı > Veri Erişimi (Kapsam ekle veya kaldır) bölümündeki OAuth kullanıcı rızası ekranına eklediniz.
    • OAuth kullanıcı rızası ekranı yayınlama durumunuz Test ediliyor (varsayılan) olarak ayarlanmışsa MCP sunucusuna bağlanan Google Hesaplarını API'ler ve Hizmetler > OAuth kullanıcı rızası ekranı > Kitle (Test kullanıcıları > + Kullanıcı ekle) bölümünde Test kullanıcıları olarak eklemişsinizdir.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: OAuth istemci kimliğine karşılık gelen OAuth istemci gizli anahtarı.
  • GOOGLE_ADS_MCP_BASE_URL: MCP sunucunuza erişilebilen herkese açık ana URL (ör. https://google-ads-mcp-xyz-uc.a.run.app). Google Cloud Run, bu URL'yi ilk dağıtım sırasında oluşturduğundan önce bu değişken olmadan dağıtım yapın, ardından dağıtımdan sonra hizmeti güncelleyin.
  • FASTMCP_HOST: FastMCP'nin tüm IP adreslerinden gelen bağlantıları kabul etmesine izin vermek için bu değeri 0.0.0.0 olarak ayarlayın.

Hizmeti Google Cloud Run'a dağıtın:

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"

Cloud Run dağıtımı tamamladıktan sonra, atanan hizmet URL'sini alın ve hizmeti GOOGLE_ADS_MCP_BASE_URL ortam değişkeniyle güncelleyin:

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"

Kimlik doğrulama ve güvenlik modeli

--allow-unauthenticated ile dağıtım yapıldığında Cloud Run'ın altyapı düzeyindeki IAM kontrolü (roles/run.invoker) devre dışı bırakılır. Böylece harici yapay zeka istemcileri, Google Cloud hizmet hesabı jetonlarına ihtiyaç duymadan bağlanabilir. Kimlik doğrulama, uygulama katmanına devredilir:

  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID ve GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET sağlandığında MCP sunucusu, gelen tüm isteklerde Google OAuth 2.0'ı zorunlu kılar ve kimliği doğrulanmamış arayanlara HTTP 401 yanıtı gönderir. Tüm araç istekleri, kimliği doğrulanmış arayanın OAuth kimliği altında yürütülür.
  • --allow-unauthenticated parametresinin kullanılmaması, Cloud Run altyapısı IAM'sini zorunlu kılar. Bu durumda, arayanların her istekte Google Cloud OIDC kimlik jetonlarını iletmesi gerekir. Standart yapay zeka istemcileri (ör. Claude ve ChatGPT), Google Cloud IAM kimlik jetonları yerine son kullanıcı OAuth'u kullanarak kimlik doğrulaması yapar. Bu nedenle, bu platformlardan doğrudan bağlantılar için uygulama düzeyinde OAuth ile --allow-unauthenticated gerekir.

MCP istemcisini yapılandırma

Dağıtımdan sonra MCP istemcinizi Cloud Run URL'si ile yapılandırın. Sunucu, OAuth 2.0 kimlik doğrulaması gerektirdiğinden istemcinin MCP OAuth akışını desteklemesi veya yetkili bir hamiline ait jeton sağlaması gerekir:

  • OAuth özellikli istemciler: MCP OAuth keşfini destekleyen istemcilerde (ör. Antigravity) uç noktaya bağlanıldığında Google ile oturum açmak ve https://www.googleapis.com/auth/adwords kapsamını (Google Cloud Console'da .../auth/adwords olarak listelenir) vermek için bir kimlik doğrulama istemi tetiklenir.
  • Üçüncü taraf yapay zeka platformları (Claude, ChatGPT): İstemcinizin bağlayıcı veya entegrasyon ayarlarında, /mcp yolunu içeren Cloud Run URL'nizi (ör. https://your-cloud-run-url.a.run.app/mcp) işaret eden özel bir bağlayıcı ekleyin, OAuth 2.0 kimlik doğrulamasını (kendi OAuth istemci kimliğinizi ve istemci gizli anahtarınızı kullanarak) seçin ve istemcinin geri çağırma URI'sinin OAuth istemcinizin yetkili yönlendirme URI'lerine eklendiğinden emin olun. (Barındırılan uç nokta pilot programının izin verilenler listesindeki katılımcıları, barındırılan MCP kurulum kılavuzuna da bakabilir.)
  • OAuth desteği olmayan istemciler: HTTP OAuth akışlarını desteklemeyen istemciler, HTTP 401 yetkisiz yanıtı alır. Bu araçlar için yerel stdio yapılandırmasını kullanın.

OAuth özellikli bir istemci için örnek yapılandırma (ör. ~/.gemini/settings.json):

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

Temel özellikler (araçlar)

Sunucu, hesap keşfi ve performans raporlaması için tasarlanmış araçlar sunar:

  • list_accessible_customers: Kimliği doğrulanmış kullanıcının erişebileceği Google Ads müşteri kimliklerinin ve hesap adlarının listesini döndürür.
  • search: Kaynak metriklerini, bütçeleri ve durumu getirmek için GAQL isteklerini yürütür.

  • get_resource_metadata: Bir Google Ads API kaynak türü (ör. "campaign") hakkında meta verileri alır.

    Bu, verilerin yapısını ve sorgulama için hangi alanların kullanılabileceğini anlamak açısından yararlıdır.

Başlangıç için örnek istemler

Sunucunun neler yapabileceğini sorma:

What can the google-ads-mcp server do?

Müşteriler hakkında soru sorma:

What customers do I have access to?

Kampanyalar hakkında soru sorma:

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

Sonraki adımlar