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

Model Bağlam Protokolü (MCP), Büyük Dil Modelleri'nin (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 standartlaştırılmış bir köprü sağlar. Bu köprü, yapay zeka temsilcilerinin doğal dili kullanarak kampanya verilerini analiz etmesine ve almasına olanak tanır.

Topluluk kaynakları ve desteği

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.

Başlıca özellikler

  • Protokol: MCP (Model Bağlam Protokolü)
  • Mod: Salt okunur (mevcut sürüm)
  • Dil: Python
  • Aktarım: Standart giriş/çıkış (stdio) veya HTTP/SSE (Cloud Run)
  • Kimlik doğrulama: OAuth 2.0 veya hizmet hesabı

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

  1. İstek: Bir kullanıcı "Kampanya performansım bu hafta nasıl?" gibi bir sorgu gönderiyor.
  2. Keşif: LLM, mevcut araçlarını inceler ve google-ads-mcp arama özelliklerini belirler.
  3. Yürütme: MCP sunucusu, Google Ads API'yi sorgulamak için temel Python mantığını yürütür.
  4. Bağlam yerleştirme: Yapılandırılmış sonuçlar, LLM'nin bağlam penceresine döndürülür.
  5. Yanıt: LLM, verileri insan tarafından okunabilecek bir yanıta dönüştürür.

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 bilgilerine sahip olduğunuzdan emin olun:

Yapılandırma

Sunucuyu MCP ile 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'ı 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'ı da 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"
      }
    }
  }
}

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. Bu seçenek, sunucuyu farklı aracılarla paylaşmak veya web hizmeti olarak çalıştırmak isterseniz yararlı olur.

Ön koşullar

  1. Google Cloud projesi.

  2. gcloud komut satırı aracı yüklendi, kimliği doğrulandı ve etkin bir proje yapılandırıldı:

    gcloud config set project YOUR_PROJECT_ID

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

Cloud Build'ü kullanarak görüntüyü yerel olarak Docker'ın yüklü olmasına gerek kalmadan Artifact Registry'ye derleyip gönderebilirsiniz.

  1. Artifact Registry'de depo oluşturma:

    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şturup gönderin:

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

    Bu adımın, dağıtılan sunucuyu en son sürüme güncellemek istediğiniz her seferde gerçekleştirilmesi 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: MCP sunucusunun kullanmasını istediğiniz OAuth istemci kimliği.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: MCP sunucusunun kullanmasını istediğiniz OAuth istemci gizli anahtarı.
  • GOOGLE_ADS_MCP_BASE_URL: MCP sunucunuza erişilebilen temel URL. Bu URL, ilk dağıtımınızdan sonra Google Cloud Run tarafından otomatik olarak atanır. Ortam değişkenlerini dağıtımdan sonra güncelleyebilirsiniz.
  • FASTMCP_HOST: FastMCP'nin tüm IP adreslerinden gelen bağlantıları kabul etmesine izin vermek için bunu 0.0.0.0 olarak ayarlayı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,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0"

MCP istemcisini yapılandırma

Dağıtımdan sonra, Cloud Run URL'sini kullanmak için MCP istemci yapılandırmanızı (örneğin, ~/.gemini/settings.json) güncelleyin.

{
  "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şebildiğ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 Google Ads Sorgu Dili (GAQL) isteklerini yürütür.

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

    Bu, verilerin yapısını ve hangi alanların sorgulanabileceğini anlamak için yararlıdır.

Başlamak için örnek istemler

Sunucunun neler yapabileceğini sorun:

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 sorun:

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