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ğlar. Yapay zeka ajanlarının doğal dil kullanarak hesap verilerini alıp analiz etmesine, öğe oluşturmasına, video yüklemesine ve etiketleri yönetmesine olanak tanır.

Topluluk kaynakları ve destek

• GitHub deposu: google-ads-mcp deposunda demolar ve örnekler bulabilir, hataları bildirebilir veya özellik önerebilirsiniz.

  Hata raporları ve özellik istekleri için Sorunlar sekmesini kullanın.

• Topluluk: Google Reklamcılık Topluluğu Discord'undaki #ads-api-ai-tools kanalına katılın.

Teknik genel bakış

Google Ads MCP sunucusunu entegre ettiğinizde Google Ads API kimlik doğrulaması, kaynak getirme, veri ayrıştırma ve desteklenen öğe veya etiket mutasyonları için özel kod yazmanız gerekmez. Sunucu, bir LLM'nin inceleyip çağırabileceği çağrılabilir araçları ve referans kaynakları (Temel özellikler bölümüne bakın) gösterir.

Temel özellikler

• Protokol: MCP (Model Context Protocol)
• Mod: Okuma ve kısmi değişiklik (öner ve onayla doğrulaması ile öğe oluşturma, video yükleme ve etiket yönetimi veya yapılandırılabilir salt okunur mod)
• Dil: Python 3.10 veya sonraki sürümler
• Taşıma: Standart giriş/çıkış (stdio) veya akış özellikli HTTP (Cloud Run'da streamable-http)
• Kimlik doğrulama: Yerel stdio için Uygulama Varsayılan Kimlik Bilgileri (OAuth 2.0 kullanıcı kimlik bilgileri veya hizmet hesabı) ya da uzak HTTP için OAuth 2.0 web uygulaması kimlik bilgileri

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

1. İstek: "Kampanyamın bu haftaki performansı nasıl?" veya "Yaz indirimimiz için açıklama metni öğesi oluştur" gibi bir istem gönderirsiniz.
2. Keşif: LLM, mevcut araçlarını ve kaynaklarını inceleyerek eşleşen bir google-ads-mcp aracını seçer.
3. Yürütme veya deneme doğrulaması: Okuma araçları, Google Ads API'yi doğrudan sorgular. Mutate araçları, değişiklikleri uygulamadan girişleri doğrulamak için önce öneri modunda (validate_only=True) çalıştırılır (Öneri ve onay güvenlik iş akışı bölümüne bakın).
4. Bağlam ekleme: MCP sunucusu, yapılandırılmış sorgu sonuçlarını veya önerilen change_items girişlerini ve doğrulama checksum özetini LLM'nin bağlam penceresine döndürür.
5. Yanıt ve onay: LLM bir yanıt sunar veya önerilen değişiklikleri onaylamanızı ister. Onayınızın ardından LLM, değişikliği uygulamak için validate_only=False ve eşleşen checksum değeriyle mutate aracını tekrar çağırır.

Başlayın

Google Ads MCP sunucusunu yerel olarak yapılandırmak ve çalıştırmak için aşağıdaki adımları uygulayın. Paylaşılan bir uzak hizmet dağıtmak için Google Cloud'da dağıtım başlıklı makaleyi inceleyin.

Ön koşullar

Sunucuyu yapılandırmadan önce yerel ortamınızda ve Google Cloud Console'da aşağıdaki ön koşulları tamamlayın:

• Google Cloud projesi: Google Ads API'nin etkinleştirildiği bir Google Cloud projesi oluşturun veya seçin. API'yi etkinleştirdiğinizde, test hesaplarında okuma ve değiştirme iş akışlarını test etmek için test erişimi verilir. Üretim hesaplarına erişmek için Google Ads API'ye genel bakış sayfasında Explorer, Temel veya Standart erişim düzeyini kontrol edin ya da bu erişim düzeylerinden biri için başvuruda bulunun. Aksi takdirde, üretim çağrıları AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION hatasıyla başarısız olur. Google, 9 Eylül 2026'da geliştirici jetonlarını (GOOGLE_ADS_DEVELOPER_TOKEN) kullanımdan kaldıracak. OAuth istemcinizin veya hizmet hesabınızın sahibi olan Google Cloud projesi, API erişim düzeyinizi belirler.
• Kimlik bilgileri: Yerel stdio modu, bir OAuth 2.0 istemci gizli anahtarı JSON dosyasından veya Cloud projenizdeki bir hizmet hesabından alınan Uygulama Varsayılan Kimlik Bilgileri (ADC) ile kimlik doğrulaması yapar. Varsayılan kotanızı veya ADC projenizi belirtmeniz gerektiğinde GOOGLE_CLOUD_PROJECT ortam değişkenini ayarlayın. Uzak streamable-http dağıtımları için OAuth 2.0 web uygulaması istemci kimliği ve istemci gizli anahtarı gerekir (Google Cloud Run'a dağıtma başlıklı makaleyi inceleyin).
• Yerel yazılım (stdio modu için): Python 3.10 veya sonraki bir sürümü, pipx ve gcloud komut satırı aracını (kullanıcı ADC dosyaları oluşturmak için kullanılır) yükleyin.

Yapılandırma

1. API'nin etkin olduğu Google Cloud projenizdeki bir OAuth istemcisini kullanarak Uygulama Varsayılan Kimlik Bilgileri (ADC) oluşturun ve Google Ads API kapsamını ekleyin:

   gcloud auth application-default login \
     --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
     --client-id-file=PATH_TO_CLIENT_SECRET_JSON
   

   Aşağıdakini değiştirin:

   • PATH_TO_CLIENT_SECRET_JSON: OAuth 2.0 istemci gizli anahtarı JSON dosyanızın yolu.

   Bu komut, Credentials saved to file: [PATH_TO_CREDENTIALS_JSON] değerini yazdırır (Linux ve macOS'te ~/.config/gcloud/application_default_credentials.json gibi). Bunun yerine bir hizmet hesabıyla kimlik doğrulaması yapmak için bu adımı atlayın ve GOOGLE_APPLICATION_CREDENTIALS değişkenini hizmet hesabı anahtarınızın JSON dosyasına yönlendirin ya da --impersonate-service-account değişkenini gcloud auth application-default login değişkenine iletin.

2. Sunucuyu, ana makinenizin MCP yapılandırma dosyasına (ör. ~/.gemini/config/mcp_config.json, ~/.gemini/settings.json veya ~/.claude/settings.json) ekleyin:

   {
     "mcpServers": {
       "google-ads-mcp": {
         "command": "pipx",
         "args": [
           "run",
           "--spec",
           "google-ads-mcp==0.0.6",
           "google-ads-mcp"
         ],
         "env": {
           "GOOGLE_CLOUD_PROJECT": "PROJECT_ID",
           "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON"
         }
       }
     }
   }
   

   Aşağıdakini değiştirin:

   • PROJECT_ID: Google Cloud proje kimliğiniz.
   • PATH_TO_CREDENTIALS_JSON: 1. adımda yazdırılan ADC JSON dosyasının veya hizmet hesabı anahtarı JSON dosyanızın yolu. Varsayılan gcloud ADC dosya konumunu kullanırken GOOGLE_APPLICATION_CREDENTIALS parametresini atlayabilirsiniz.

   Müşteri hesaplarına bir yönetici hesabı üzerinden erişmek için env içinde GOOGLE_ADS_LOGIN_CUSTOMER_ID (tire olmadan 10 haneli) değerini ayarlayın veya her bir araç çağrısında login_customer_id parametresini iletin.

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

Google Ads MCP sunucusu, yapay zeka istemcinize hesap raporlama verilerine canlı erişim imkanı sunar. Ayrıca öğe oluşturma, video yükleme ve etiket yönetimi araçlarına da erişim sağlar. Temsilcinizin geçerli Google Ads Sorgu Dili (GAQL) sorguları oluşturmasına ve hesap performansındaki değişiklikleri teşhis etmesine yardımcı olmak için MCP sunucusunu aşağıdaki tamamlayıcı araçlarla eşleyin. Bu araçlar, oluşturulan öğeleri kampanyalara bağlamak veya desteklenmeyen diğer mutasyonları gerçekleştirmek için komut dosyaları gibi istemci kitaplığı kodları da oluşturur:

• Google Ads API temsilci becerileri: Temsilcinizin Google Ads MCP sunucusunu daha düşük jeton ek yüküyle kullanmasına yardımcı olan taşınabilir iş akışı modülleri (google-ads-api-mcp-setup, google-ads-api-account-diagnostics ve google-ads-api-quickstart dahil). Bunları yüklemek için aşağıdaki komutu çalıştırın (Node.js gerekir) veya Antigravity, Claude Code, Codex ve Cursor kurulumu 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 şema denetimi, GAQL doğrulaması, istemci kitaplığı kod oluşturma ve çevrimdışı dönüşüm sorunlarını giderme özellikleri sunan modüler bir eklentidir. Google Ads API Developer Assistant nedir? başlıklı makaleyi okuyun veya kurulum kılavuzundaki adımları uygulayın.

Temel özellikler

Aşağıdaki bölümlerde sunucunun okuma araçları, kısmi mutasyon araçları ve referans kaynakları açıklanmaktadır. v0.0.6 sürümünden itibaren araçlar varsayılan olarak kategori ad alanı önekleriyle (ör. search_search) kaydedilir. Önek içermeyen sürümlerden istemleri veya izin verilenler listelerini yükseltirken araç adlarını güncelleyin ya da tools_config.yaml içinde boş bir önek ("") ayarlayın (Araç ad alanlarını ve salt okunur modu yapılandırma bölümüne bakın).

Okuma araçları

• customers_list_accessible_customers (araç list_accessible_customers): Kimliği doğrulanmış kullanıcının doğrudan erişebileceği Google Ads müşteri kimliklerini döndürür.
• search_search (araç search): Ham GAQL dizesi yerine yapılandırılmış parametrelerden (customer_id, resource ve fields ile isteğe bağlı conditions, orderings, limit ve login_customer_id) GAQL SearchStream sorguları oluşturur ve çalıştırır. Her sorgu, kaynak özelliklerini, metrikleri, segmentleri, bütçeleri ve durumu net bir şekilde getirmek için PARAMETERS omit_unselected_resource_names=true ekler.
• metadata_get_resource_metadata (araç get_resource_metadata): Bir Google Ads API kaynak türü (ör. "campaign") için seçilebilir, filtrelenebilir ve sıralanabilir özellikleri, metrikleri ve segmentleri alır. search_search aracını çağırmadan önce, v26.2 gibi küçük sürümlere eklenen metrikler ve segmentler de dahil olmak üzere geçerli sorgu alanlarını keşfetmek için bu meta verileri kullanın.

Değişiklik araçları (kısmi destek)

• assets_create_asset (araç create_asset): TEXT, IMAGE, YOUTUBE_VIDEO, SITELINK, CALLOUT ve STRUCTURED_SNIPPET öğe türleri için özel parametreler içeren bağımsız Google Ads öğeleri oluşturur. Diğer değişken AssetService türleri (ör. PRICE, PROMOTION, CALL veya BUSINESS_MESSAGE) için extra_params sözlüğünü iletin ve SITELINK öğeleri için sitelink_link_text ile birlikte kök düzeyinde final_urls ekleyin. Yerel dosya yolları (image_asset_path) yalnızca yerel stdio modunda çalışır. Uzak HTTP dağıtımları için base64 olarak kodlanmış image_asset_data parametresini IMAGE_PNG, IMAGE_JPEG veya IMAGE_GIF (en fazla 20 MB) olarak ayarlanmış image_asset_mime_type ile iletin.
• assets_upload_video_asset (araç upload_video_asset): Yalnızca yerel stdio modunda Google Ads API aracılığıyla YouTube'a yerel bir video dosyası yükler (.3gp, .avi, .flv, .mkv, .mov, .mp4, .mpeg, .mpg, .ogg, .webm veya .wmv). Hem video_title hem de video_description zorunlu parametrelerdir ve gizlilik varsayılan olarak UNLISTED (veya kullanıcı OAuth'u olan reklamverene ait marka kanallarında PUBLIC) şeklindedir. Bu araç, 11 karakterlik YouTube video_id değerini değil, Google Ads video_upload_id değerini (ve kaynak adını) döndürür. you_tube_video_upload sorgusunu search_search aracıyla (you_tube_video_upload.video_upload_id ölçütüne göre filtreleyerek) you_tube_video_upload.state = 'PROCESSED' tarihine kadar sorgulayın. Ardından you_tube_video_upload.video_id'i assets_create_asset (asset_type="YOUTUBE_VIDEO") için youtube_video_id parametresi olarak geçirin.
• labels_manage_labels (araç manage_labels): Ad, açıklama ve onaltılık arka plan rengi dahil olmak üzere hesap etiketlerini oluşturur, günceller ve kaldırır.
• labels_manage_label_associations (araç manage_label_associations): CAMPAIGN, CUSTOMER, AD_GROUP ve AD_GROUP_CRITERION kaynaklarında CREATE ve REMOVE etiket ilişkilendirme işlemlerini destekler (UPDATE desteklenmez). CUSTOMER kaynakları için resource_id isteğe bağlıdır ve varsayılan olarak customer_id değerine ayarlanır. AD_GROUP_CRITERION kaynakları için bileşik bir {ad_group_id}~{criterion_id} kimliği iletin ve resource_id ile label_id veya association_resource_name değerini ileterek ilişkilendirmeleri kaldırın. Reklam düzeyinde AD_GROUP_AD etiketler desteklenmez.

Referans kaynaklar

Sunucu, tools_config.yaml ayarlarınızdan bağımsız olarak bağlı kalan dört salt okunur MCP kaynağı sunar:

• resource://discovery-document: Google Ads API kaynakları, hizmet yöntemleri ve şemalarının JSON REST keşfine genel bakış. Seçilebilir, filtrelenebilir ve sıralanabilir GAQL sorgu alanları döndüren metadata_get_resource_metadata aracını tamamlar.
• resource://metrics: Google Ads API metrikleri için HTML referans belgeleri.
• resource://segments: Google Ads API segmentleri için HTML referans belgeleri.
• resource://release-notes: Sürüm değişikliklerini ve yeni özellikleri kapsayan HTML Google Ads API sürüm notları.

Öneri ve onay güvenlik iş akışı

Her bir değiştirme aracı (assets_create_asset, assets_upload_video_asset, labels_manage_labels ve labels_manage_label_associations), istenmeyen hesap değişikliklerini önlemeye yardımcı olmak için iki adımlı bir önerme ve onaylama iş akışı uygular:

1. Öner (validate_only=True, varsayılan): Değişiklikleri uygulamadan girişleri doğrular. Öğe ve etiket araçları, canlı bir Google Ads API validate_only deneme çalıştırması yürütür. YouTubeVideoUploadService aracının deneme modu olmadığından assets_upload_video_asset, yerel dosyayı doğrular ve boyutunu ve değişiklik zaman damgasını bağlar. Her araç, kullanıcı tarafından okunabilen change_items girişleri ve customer_id parametresi ile istek yüküne bağlı durum bilgisiz bir SHA-256 checksum özeti döndürür.
2. Onaylama (validate_only=False): change_items listesini sunduktan ve onayınızı aldıktan sonra ajan tabanlı telefon araması, validate_only=False, aynı customer_id parametresi ve bağımsız değişkenleri ve 1. adımdaki checksum değeriyle aracı tekrar çağırır. Sunucu, hesapta değişiklik yapmadan önce eksik veya eşleşmeyen denetim toplamlarını reddeder.

Araç ad alanlarını ve salt okunur modu yapılandırma

Sunucu, beş araç kategorisinin (customers, search, metadata, labels ve assets) tümü etkinleştirilmiş varsayılan bir tools_config.yaml dosyası içerir. tools_config.yaml dosyasını özelleştirerek araçları veya ad alanlarını tek tek etkinleştirebilir ya da devre dışı bırakabilir, ad alanı ön eklerini değiştirebilir veya kaldırabilir ya da salt okunur dağıtımı zorunlu kılabilirsiniz.

Başlangıçta sunucu, tools_config.yaml değerini aşağıdaki sırayla çözümler:

1. GOOGLE_ADS_MCP_TOOLS_CONFIG ortam değişkeninde açık bir yol (çalışma dizini proje klasörünüzden farklı olabilen yerel stdio ana makineleri için önerilir).
2. Sunucunun geçerli çalışma dizininde bir tools_config.yaml dosyası.
3. Paketle birlikte gelen varsayılan tools_config.yaml dosyası.

GOOGLE_ADS_MCP_TOOLS_CONFIG eksik bir dosyaya işaret ediyorsa veya çözümlenen yapılandırma dosyalarından herhangi biri geçersizse sunucu, varsayılan ayarlara geri dönmek yerine başlangıçta bir hata verir.

Aşağıdaki minimal tools_config.yaml dosyası, kesinlikle salt okunur bir dağıtım uygular:

namespaces:
  customers: true
  search: true
  metadata: true
  labels: false
  assets: false

Aşağıdaki tools_config.yaml dosyası, önekleri özelleştirir ve her bir aracı filtreler (örneğin, yalnızca yerel upload_video_asset aracını devre dışı bırakırken Cloud Run'da base64 create_asset aracını gösterir):

namespaces:
  # Default prefix ("customers_list_accessible_customers")
  customers: true

  # Empty prefix mounts unprefixed tool names ("search")
  search: ""

  # Custom prefix ("schema_get_resource_metadata")
  metadata: "schema"

  # Enable only specific tools in a multi-tool category
  assets:
    enabled_tools:
      - create_asset

Başlamak için örnek istemler

Sunucuyu bağladıktan sonra MCP istemcinizde aşağıdaki istemleri deneyin.

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

Öğe oluşturma, video yükleme ve etiketleri yönetme

Create a callout asset with the text "Free Shipping" for account 1234567890

Upload /path/to/promo.mp4 with title "Summer Sale" and description "Summer promo video" for account 1234567890

Create a label named "Q4 Promo" with background color #34A853 and apply it to campaign 9876543210 in account 1234567890

Google Cloud'da dağıtım

MCP sunucusunu birden fazla temsilciyle paylaşmak veya web hizmeti olarak çalıştırmak için yerel olarak çalıştırmak yerine Google Cloud Run'da ya da başka bir bulut altyapısı sağlayıcısında barındırın.

Ön koşullar

1. Google Ads API'nin etkinleştirildiği bir Google Cloud projesi (Üretim erişimi şartları için Ön koşullar bölümüne bakın).

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

   gcloud config set project PROJECT_ID
   

   Aşağıdakini değiştirin:

   • PROJECT_ID: Google Cloud proje kimliğiniz.

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

Docker'ı yerel olarak yüklemeden container görüntüsünü derlemek ve Artifact Registry'ye aktarmak için Cloud Build'i kullanın:

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

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

2. GitHub deposundaki bir sürüm etiketinden (veya Dockerfile ya da tools_config.yaml'yi özelleştirdiyseniz yerel bir kopyadaki . dizininden) görüntüyü derleyip gönderin:

   gcloud builds submit https://github.com/googleads/google-ads-mcp \
     --git-source-revision=v0.0.6 \
     --tag=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6
   

   Aşağıdakini değiştirin:

   • PROJECT_ID: Google Cloud proje kimliğiniz.

   google-ads-mcp öğesini her güncellediğinizde veya yeni Google Ads API sürümleri (ör. v26.2) için paket halindeki google-ads Python istemci kitaplığını her yükselttiğinizde görüntüyü yeniden oluşturun ve yeniden dağıtın.

Google Cloud Run'a dağıt

Cloud Run hizmetiniz için aşağıdaki ortam değişkenlerini ve gizli anahtarları yapılandırın:

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Uygulama düzeyinde OAuth kimlik doğrulaması için API özellikli Google Cloud projenizden OAuth 2.0 web uygulaması istemci kimliği. Aşağıdaki OAuth yapılandırma adımlarını tamamlayın:
  • 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 yetkilendirilmiş yönlendirme URI'lerini ekleyin.
  • 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 ekleyin.
  • 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 ekleyin.
• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: OAuth istemci kimliğinize karşılık gelen OAuth istemci gizli anahtarı.
• GOOGLE_ADS_MCP_BASE_URL: MCP sunucunuzun herkese açık ana URL'si (ör. https://google-ads-mcp-xyz-uc.a.run.app). Cloud Run, bu URL'yi ilk dağıtım sırasında atar. Bu nedenle, önce bu değişken olmadan dağıtım yapın ve ardından hizmeti güncelleyin.
• GOOGLE_ADS_MCP_JWT_SIGNING_KEY (aynı anda çalışan birden çok kopya Cloud Run için önerilir): Container yeniden başlatmaları ve yatay ölçeklendirme sırasında FastMCP JWT'lerini imzalayan kalıcı bir gizli anahtar.
• GOOGLE_ADS_MCP_STORAGE_TYPE (aynı anda çalışan birden çok kopyalı Cloud Run için önerilir): OAuth istemci kayıtları ve jetonları için kalıcı arka uç (GOOGLE_ADS_MCP_STORAGE_REDIS_URL ile redis veya firestore). Stok v0.0.6 Dockerfile yalnızca bellek içi arka ucu yüklediğinden, önce özel bir Dockerfile'e py-key-value-aio[redis] veya .[firestore] yükleyin. firestore özelliğini kullanmak için bir Firestore veritabanı ve Cloud Run hizmet hesabında roles/datastore.user IAM rolü de gerekir. Bellek içi depolama ile tek örnekli test için --max-instances=1 değerini iletin.
• GOOGLE_ADS_LOGIN_CUSTOMER_ID (isteğe bağlı): Araç çağrıları login_customer_id parametresini atladığında kullanılan varsayılan 10 haneli yönetici müşteri kimliği (tire işareti olmadan).
• GOOGLE_ADS_MCP_TOOLS_CONFIG (isteğe bağlı): Özel bir tools_config.yaml dosyasının kapsayıcı yolu (ör. görüntüyü yeniden oluşturmadan salt okunur modu zorunlu kılmak için /etc/mcp/tools_config.yaml adresindeki Secret Manager'dan bağlanır). Araç ad alanlarını ve salt okuma modunu yapılandırma bölümüne bakın.

GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET ve GOOGLE_ADS_MCP_JWT_SIGNING_KEY değerlerini Secret Manager'da depolayın ve hizmeti Google Cloud Run'a dağıtın:

gcloud run deploy google-ads-mcp \
  --image=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6 \
  --platform=managed \
  --region=us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=CLIENT_ID" \
  --set-secrets="GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=MCP_OAUTH_CLIENT_SECRET:latest,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=MCP_JWT_SIGNING_KEY:latest"

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://CLOUD_RUN_SERVICE_URL"

Aşağıdakini değiştirin:

• PROJECT_ID: Google Cloud proje kimliğiniz.
• CLIENT_ID: OAuth 2.0 web uygulaması istemci kimliğiniz.
• MCP_OAUTH_CLIENT_SECRET: OAuth 2.0 istemci gizli anahtarınızı depolayan Secret Manager gizli anahtar adı.
• MCP_JWT_SIGNING_KEY: JWT imzalama anahtarınızı depolayan Secret Manager gizli adı.
• CLOUD_RUN_SERVICE_URL: Cloud Run hizmetinize atanan ana makine adı (ör. google-ads-mcp-xyz-uc.a.run.app).

Kimlik doğrulama ve güvenlik modeli

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

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID ve GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET ayarlandığında sunucu, her istekte Google OAuth 2.0'ı zorunlu kılar ve kimliği doğrulanmamış arayanlara 401 Unauthorized HTTP durum kodu döndürür. Her araç çağrısı, kimliği doğrulanmış arayanın OAuth kimliği altında yürütülür.
• --allow-unauthenticated atlanırsa arayanların her istekte Google Cloud OIDC kimlik jetonlarını iletmesi gerekir. Standart yapay zeka istemcileri (ör. Claude ve ChatGPT), Google Cloud IAM jetonları yerine son kullanıcı OAuth'u kullandığından doğrudan bağlantılar için uygulama düzeyinde OAuth ile eşlenmiş --allow-unauthenticated gerekir.

MCP istemcisini yapılandırma

Dağıtımdan sonra MCP istemcinizi Cloud Run hizmet URL'si ile yapılandırın. Sunucu, OAuth 2.0'ı zorunlu kıldığı için istemciniz MCP OAuth akışını desteklemeli veya yetkili bir hamiline ait jeton sağlamalıdır:

• OAuth özellikli istemciler: MCP OAuth keşfini destekleyen istemcilerde (ör. Antigravity) bağlantı kurulduğunda https://www.googleapis.com/auth/adwords kapsamını (Google Cloud Console'da .../auth/adwords olarak gösterilir) vermek için Google oturum açma istemi tetiklenir.
• Üçüncü taraf yapay zeka platformları (Claude, ChatGPT): İstemcinizin bağlayıcı ayarlarında, /mcp yoluyla hizmet URL'nizi işaret eden özel bir bağlayıcı ekleyin (ör. https://google-ads-mcp-xyz-uc.a.run.app/mcp). OAuth istemci kimliğiniz ve istemci gizli anahtarınızla OAuth 2.0 kimlik doğrulamasını seçin ve istemcinin geri çağırma URI'sinin OAuth istemcinizin yetkili yönlendirme URI'lerinde olduğunu onaylayın.
• OAuth desteği olmayan istemciler: HTTP OAuth akışlarını desteklemeyen istemciler 401 Unauthorized HTTP durum kodu alır. Bu istemciler için yerel stdio yapılandırmasını kullanın.

Aşağıdaki örnekte, ~/.gemini/settings.json bölgesinde gemini komut satırı aracı yapılandırılmaktadır (~/.gemini/config/mcp_config.json bölgesindeki Google Antigravity için "httpUrl" yerine "serverUrl" veya "url" yazın):

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://CLOUD_RUN_SERVICE_URL/mcp"
    }
  }
}

Aşağıdakini değiştirin:

• CLOUD_RUN_SERVICE_URL: Cloud Run hizmetinize atanan ana makine adı (ör. google-ads-mcp-xyz-uc.a.run.app).

Sonraki adımlar

• Google Ads API temsilci becerilerini yükleme
• Google Ads API Geliştirici Asistanı hakkında bilgi
• Google Ads API Developer Assistant'ı yükleme ve kullanma