Google Ads MCP Server 🚀

Google Ads API ile Model Context Protocol sunucusu, otomatik OAuth 2.0 kimlik doğrulaması ile FastMCP tarafından destekleniyor

Google Ads API'sini Claude Desktop ve diğer MCP istemcilerine sorunsuz OAuth 2.0 kimlik doğrulaması, otomatik token yenileme, GAQL sorgulama ve anahtar kelime araştırması yetenekleriyle bağlayın.

Kolay Tek Tıklamalı Kurulum

Daha basit bir kurulum deneyimi için hazır kullanılabilir yükleyiciler sunuyoruz:

👉 Yükleyiciyi indir - https://gomarble.ai/mcp

Yardım ve güncellemeler için topluluğumuza katılın

👉 Slack Community - AI in Ads

Facebook ads MCP sunucusunu da deneyin

👉 Facebook Ads MCP - Facebook Ads MCP

✨ Özellikler

• 🔐 Otomatik OAuth 2.0 - Tek seferlik tarayıcı kimlik doğrulaması ve otomatik yenileme
• 🔄 Akıllı Token Yönetimi - Süresi dolmuş tokenları otomatik olarak işler
• 📊 GAQL Query Yürütme - Herhangi bir Google Ads Query Language sorgusunu çalıştırın
• 🏢 Hesap Yönetimi - Google Ads hesaplarını listeleyin ve yönetin
• 🔍 Anahtar Kelime Araştırması - Arama hacmi verileriyle anahtar kelime fikirleri oluşturun
• 🚀 FastMCP Framework - Modern MCP standardı üzerine inşa edildi
• 🖥️ Claude Desktop Hazırlandı - Claude Desktop ile doğrudan entegrasyon
• 🛡️ Güvenli Yerel Depolama - Tokenler yerel olarak depolanır, asla açıklanmaz

📋 Kullanılabilir Araçlar

Araç	Açıklama	Parametreler	Örnek Kullanım
list_accounts	Tüm erişilebilir Google Ads hesaplarını listele	Yok	"Tüm Google Ads hesaplarımı listele"
run_gaql	Özel biçimlendirme ile GAQL sorguları yürüt	customer_id, query, manager_id (isteğe bağlı)	"Hesap 1234567890 için kampanya performansını göster"
run_keyword_planner	Metriklerle anahtar kelime fikirleri oluştur	customer_id, keywords, manager_id, page_url, tarih aralığı seçenekleri	"'dijital pazarlama' için anahtar kelime fikirleri oluştur"

Not: Tüm araçlar otomatik olarak kimlik doğrulamayı işler - token parametreleri gerekli değildir!

🚀 Hızlı Başlangıç

Ön Koşullar

MCP sunucusunu kurmadan önce şunlara ihtiyacınız olacak:

• Python 3.10+ yüklü
• Bir Google Cloud Platform hesabı
• API erişimi olan bir Google Ads hesabı

🔧 Adım 1: Google Cloud Platform Kurulumu

1.1 Google Cloud Projesi Oluştur

1. Google Cloud Console adresine git
2. Yeni bir proje oluştur:
   • "Proje seç" → "Yeni Proje" seçeneğine tıkla
   • Proje adını gir (örneğin, "Google Ads MCP")
   • "Oluştur" seçeneğine tıkla

1.2 Google Ads API'sini Etkinleştir

1. Google Cloud Console'unda:
   • "APIs & Services" → "Library" seçeneğine git
   • "Google Ads API" ara
   • Üzerine tıkla ve "Enable" seçeneğine bas

1.3 OAuth 2.0 Kimlik Bilgilerini Oluştur

1. "APIs & Services" → "Credentials" seçeneğine git
2. "+ CREATE CREDENTIALS" → "OAuth 2.0 Client ID" seçeneğine tıkla
3. Onay ekranını yapılandır (ilk kez ise):
   • "Configure Consent Screen" seçeneğine tıkla
   • "External" seçeneğini seç (Google Workspace'e sahip olmadığınız sürece)
   • Gerekli alanları doldur:
     • Uygulama adı: "Google Ads MCP"
     • Kullanıcı destek e-postası: Senin e-postanız
     • Geliştirici iletişim: Senin e-postanız
   • Tüm adımlardan geçerek "Save and Continue" seçeneğine tıkla
4. OAuth Client oluştur:
   • Uygulama türü: "Desktop application"
   • Ad: "Google Ads MCP Client"
   • "Oluştur" seçeneğine tıkla
5. Kimlik bilgilerini indir:
   • "Download JSON" düğmesine tıkla
   • Dosyayı proje dizininde client_secret_[long-string].json olarak kaydet

🔧 Adım 2: Google Ads API Kurulumu

2.1 Developer Token'ı Al

1. Google Ads adresinde oturum aç
2. Tools & Settings'e git (üst navigasyondaki wrench simgesi)
3. "Setup" altında "API Center" seçeneğine tıkla
4. Hizmet Şartları'nı Kabul Et (istenirse)
5. "Apply for token" seçeneğine tıkla
6. Uygulama formunu doldur:
   • Kullanım durumunu açıkla (örneğin, "MCP entegrasyonu kampanya analizi için")
   • Uygulamanız hakkında teknik detaylar sağla
7. Gönder ve onay bekle (genellikle 1-3 iş günü)

Not: İlk olarak sınırlı işlevselliğe sahip bir test token'ı alacaksınız. Test ettikten sonra, üretim erişimi için başvurabilirsiniz.

2.2 Developer Token'ınızı Bulun

Onay aldıktan sonra:

1. Google Ads'te API Center'a dön
2. Developer Token'ınızı kopyala (format: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)

🔧 Adım 3: Kurulum ve Ayar

3.1 Klonla ve Yükle

# Depoyu klonla
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# Sanal ortam oluştur (önerilir)
python3 -m venv .venv
source .venv/bin/activate  # Windows'ta: .venv\Scripts\activate

# Bağımlılıkları yükle
pip install -r requirements.txt

3.2 Ortam Yapılandırması

Proje dizininde bir .env dosyası oluştur:

# Örnek dosyayı kopyala
cp .env.example .env

.env dosyasını kimlik bilgilerinizle düzenle:

# Gerekli: Google Ads API Developer Token
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here

# Gerekli: OAuth kimlik bilgileri JSON dosyasının yolu (Google Cloud'dan indirildi)
GOOGLE_ADS_OAUTH_CONFIG_PATH=/full/path/to/your/client_secret_file.json

Örnek .env dosyası:

GOOGLE_ADS_DEVELOPER_TOKEN=ABCDEFG1234567890
GOOGLE_ADS_OAUTH_CONFIG_PATH=/Users/john/google-ads-mcp/client_secret_138737274875-abc123.apps.googleusercontent.com.json

🖥️ Adım 4: Claude Desktop Entegrasyonu

4.1 Claude Yapılandırmasını Bulun

Claude Desktop yapılandırma dosyanızı bulun:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

4.2 MCP Sunucusu Yapılandırmasını Ekle

Yapılandırma dosyasını düzenle ve Google Ads MCP sunucusunu ekle:

{
  "mcpServers": {
    "google-ads": {
      "command": "/full/path/to/your/project/.venv/bin/python",
      "args": [
        "/full/path/to/your/project/server.py"
      ]
    }
  }
}

Gerçek Örnek:

{
  "mcpServers": {
    "google-ads": {
      "command": "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/.venv/bin/python",
      "args": [
        "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/server.py"
      ]
    }
  }
}

Önemli:

• Tüm dosya konumları için mutlak yollar kullan
• Windows'ta, yollarda ileri eğik çizgi / veya çift backslash \\ kullan
• your_developer_token_here değerini gerçek developer token'ınızla değiştir

4.3 Claude Desktop'ı Yeniden Başlat

Yeni yapılandırmayı yüklemek için Claude Desktop'ı kapatıp yeniden başlat.

🔐 Adım 5: İlk Kimlik Doğrulama

5.1 OAuth Akışını Tetikle

1. Claude Desktop'ı aç
2. Herhangi bir Google Ads komutunu dene, örneğin:

   "Tüm Google Ads hesaplarımı listele"
   

5.2 Kimlik Doğrulamayı Tamamla

1. Tarayıcı otomatik olarak açılır Google OAuth sayfasına
2. Oturum aç Google hesabınızla (Google Ads erişimi olan)
3. İzinleri ver "Allow" seçeneğine tıkla
4. Tarayıcı başarı sayfasını gösterir
5. Claude'a dön - komutunuz otomatik olarak tamamlanacak!

5.3 Kurulumu Doğrula

Kimlik doğrulamadan sonra şunları görmelisiniz:

• Proje dizininizde oluşturulan google_ads_token.json dosyası
• Claude'un yanıtında listelenen Google Ads hesapları

📖 Kullanım Örnekleri

Temel Hesap İşlemleri

"Tüm Google Ads hesaplarımı listele"

"Hesap detaylarını göster ve hangi hesapların aktif kampanyaları var"

Kampanya Analizi

"Hesap 1234567890 için son 30 gün içinde kampanya performansını göster"

"Son haftada tüm kampanyaların dönüşüm verilerini al"

"En yüksek dönüşüm maliyeti olan kampanyalar hangisi?"

Anahtar Kelime Araştırması

"Hesap 1234567890'ı kullanarak 'dijital pazarlama' için anahtar kelime fikirleri oluştur"

"'AI otomasyonu' için anahtar kelime fırsatları bul ve arama hacmi verilerini göster"

"https://example.com/services sayfası için anahtar kelimeleri araştır"

Özel GAQL Sorguları

"Hesap 1234567890 için bu GAQL sorgusunu çalıştır:
SELECT campaign.name, metrics.clicks, metrics.cost_micros 
FROM campaign 
WHERE segments.date DURING LAST_7_DAYS"

"Anahtar kelime performans verilerini al:
SELECT ad_group_criterion.keyword.text, metrics.ctr, metrics.average_cpc
FROM keyword_view 
WHERE metrics.impressions > 100"

🔍 Gelişmiş GAQL Örnekleri

Gelir ile Kampanya Performansı

SELECT 
  campaign.id,
  campaign.name, 
  metrics.clicks, 
  metrics.impressions,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value
FROM campaign 
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC

Anahtar Kelime Performans Analizi

SELECT 
  campaign.name,
  ad_group_criterion.keyword.text, 
  ad_group_criterion.keyword.match_type,
  metrics.ctr,
  metrics.average_cpc,
  metrics.quality_score
FROM keyword_view 
WHERE segments.date DURING LAST_7_DAYS
  AND metrics.impressions > 100
ORDER BY metrics.conversions DESC

Cihaz Performans Dağılımı

SELECT 
  campaign.name,
  segments.device,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.status = 'ENABLED'

📁 Proje Yapısı

google-ads-mcp-server/
├── server.py                           # Ana MCP sunucusu
├── oauth/
│   ├── __init__.py                     # Paket başlatma
│   └── google_auth.py                  # OAuth kimlik doğrulama mantığı
├── google_ads_token.json               # Otomatik oluşturulan token depolama (gitignored)
├── client_secret_[long-string].json    # OAuth kimlik bilgileriniz (gitignored)
├── .env                                # Ortam değişkenleri (gitignored)
├── .env.example                        # Ortam şablonu
├── .gitignore                          # Git göz ardı dosyası
├── requirements.txt                    # Python bağımlılıkları
├── LICENSE                             # MIT Lisansı
└── README.md                           # Bu dosya

🔒 Güvenlik ve En İyi Uygulamalar

Dosya Güvenliği

• ✅ Kimlik bilgileri dosyaları gitignored - Sürüm kontrolüne asla işlenmez
• ✅ Yerel token depolama - Tokenler google_ads_token.json içinde yerel olarak depolanır
• ✅ Ortam değişkenleri - Hassas veriler .env dosyasında
• ✅ Otomatik yenileme - Minimal token maruziyeti süresi

Önerilen Dosya İzinleri

# Hassas dosyalar için güvenli izinleri ayarla
chmod 600 .env
chmod 600 google_ads_token.json
chmod 600 client_secret_*.json

Üretim Değerlendirmeleri

1. Üretimde .env dosyaları yerine ortam değişkenleri kullan
2. API kotalalarına saygı göstermek için hız sınırlandırması uygula
3. Google Cloud Console'da API kullanımını izle
4. Token depolamayı uygun erişim denetimleriyle güvenli hale getir
5. Geliştirilmiş güvenlik için düzenli token rotasyonu

🛠️ Sorun Giderme

Kimlik Doğrulama Sorunları

Sorun	Semptomlar	Çözüm
Token bulunamadı	"Starting OAuth flow" mesajı	✅ İlk kurulum için normal - tarayıcı kimlik doğrulamasını tamamla
Token yenileme başarısız	"Refreshing token failed" hatası	✅ google_ads_token.json dosyasını sil ve yeniden kimlik doğrula
OAuth akışı başarısız	Tarayıcı hatası veya yanıt yok	Kimlik bilgileri dosyası yolunu ve internet bağlantısını kontrol et
İzin reddedildi	Tarayıcıda "Access denied"	Google hesabının Google Ads erişimi olduğundan emin ol

Yapılandırma Sorunları

Sorun	Semptomlar	Çözüm
Ortam değişkenleri eksik	"Environment variable not set"	.env dosyasını ve Claude config env bölümünü kontrol et
Dosya bulunamadı	"FileNotFoundError"	Yapılandırmada mutlak yolları doğrula
Modül import hataları	"ModuleNotFoundError"	pip install -r requirements.txt çalıştır
Python yolu sorunları	"Command not found"	Python executable'a mutlak yol kullan

Claude Desktop Sorunları

Sorun	Semptomlar	Çözüm
Sunucu bağlanmıyor	Google Ads araçları kullanılamıyor	Claude Desktop'ı yeniden başlat, config dosyası sözdizimini kontrol et
Geçersiz JSON config	Claude başlangıç hataları	Config dosyasında JSON sözdizimini doğrula
İzin hataları	Başlangıçta "Permission denied"	Dosya izinlerini ve yollarını kontrol et

API Sorunları

Sorun	Semptomlar	Çözüm
Geçersiz customer ID	"Customer not found"	10 haneli format kullan tireleme olmadan: 1234567890
API kota aşıldı	"Quota exceeded" hatası	Kota sıfırlanması için bekle veya artırma iste
Geçersiz developer token	"Authentication failed"	Google Ads API Center'da token'ı doğrula
GAQL sözdizimi hataları	"Invalid query"	GAQL sözdizimini ve alan adlarını kontrol et

Hata Ayıklama Modu

Sorun giderme için ayrıntılı günlüğü etkinleştir:

# Hata ayıklama için server.py'a ekle
import logging
logging.basicConfig(level=logging.DEBUG)

Yardım Almak

Sorunlar yaşarsanız:

1. Hata mesajını dikkatle oku - genellikle tam problemi gösterir
2. Tüm dosya yollarını doğrula - mutlak ve doğru olmalı
3. Ortam değişkenlerinin ayarlandığından emin ol
4. Google Cloud Console'da API kotalarını ve faturalandırmayı kontrol et
5. Herhangi bir yapılandırma değişikliğinden sonra Claude Desktop'ı yeniden başlat

🚀 Gelişmiş Yapılandırma

HTTP Transport Modu

Web dağıtımı veya uzaktan erişim için:

# Sunucuyu HTTP modunda başlat
python3 server.py --http

HTTP için Claude Desktop config:

{
  "mcpServers": {
    "google-ads": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Özel Token Depolama

oauth/google_auth.py dosyasında token depolama konumunu değiştir:

# Özel token dosyası konumu
def get_token_path():
    return "/custom/secure/path/google_ads_token.json"

Manager Hesap Yapılandırması

MCC altında birden fazla hesabı yönetmek için:

# .env dosyasına ekle
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

🤝 Katkıda Bulunmak

Katkıları memnuniyetle karşılıyoruz! Başlamak için şunları yapın:

Geliştirme Kurulumu

# Depoyu fork'la ve klonla
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# Geliştirme ortamı oluştur
python3 -m venv .venv
source .venv/bin/activate

# Bağımlılıkları yükle
pip install -r requirements.txt

# Geliştirme ortamını ayarla
cp .env.example .env
# Geliştirme kimlik bilgilerini .env'ye ekle

Değişiklikler Yapmak

1. Feature branch'i oluştur: git checkout -b feature/amazing-feature
2. Değişiklikleri yap - uygun testlerle birlikte
3. Farklı hesap yapılandırmalarıyla iyice test et
4. Gerekli olduğu kadar dokumentasyonu güncelle
5. Değişiklikleri commit'le: git commit -m 'Add amazing feature'
6. Branch'e push'la: git push origin feature/amazing-feature
7. Detaylı açıklamayla Pull Request aç

Değişiklikleri Test Etmek

# Kimlik doğrulama akışını test et
python3 server.py --test-auth

# API bağlantısını test et
python3 -c "
from oauth.google_auth import get_oauth_credentials
creds = get_oauth_credentials()
print('✅ Authentication successful!')
"

# Claude Desktop ile test et
# Sunucuyu Claude config'e ekle ve çeşitli komutları test et

📊 API Limitleri ve Kotalar

Google Ads API Kotaları

• Temel erişim: Günde 15.000 operasyon
• Standart erişim: Günde 40.000 operasyon
• Request hızı: Developer token başına dakika başına 1.600 request

API Kullanımı için En İyi Uygulamalar

1. API çağrılarını azaltmak için mümkün olduğunda sonuçları cache'le
2. Veri hacmini sınırlamak için tarih aralıkları kullan
3. Desteklendiğinde request'leri toplu olarak gönder
4. Google Cloud Console'da kullanımı izle
5. Hız sınırı hataları için retry mantığını uygula

Kota Yönetimi

# Google Cloud Console'da kullanımı izle
# APIs & Services → Quotas adresine git
# Mevcut kullanımı görmek için "Google Ads API" ara

📄 Lisans

Bu proje MIT Lisansı altında lisanslanmıştır - detaylar için LICENSE dosyasına bakın.

---

MIT Lisansı

Telif Hakkı (c) 2025 Google Ads MCP Server Katkıda Bulunanlar

Herhangi bir kişiye, bu yazılım ve ilgili belgeleri (bundan sonra "Yazılım" olarak anılacak) 
kullanma, kopyalama, değiştirme, birleştirme, yayınlama, dağıtma, alt lisans verme ve/veya 
satma hakkı dahil olmak üzere, aşağıdaki şartlara tabi olarak hiçbir ücret ödemeden izin 
vermesi bu itiraf edilen yönetim hakkıdır:

Yukarıdaki telif hakkı bildirimi ve bu izin bildirimi, Yazılımın tüm kopyalarında veya 
önemli bölümlerinde yer almalıdır.

YAZILIM "OLDUĞU GİBİ" SAĞLANMAKTADIR. AÇIK VEYA ZIMNİ OLARAK, TİCARİLİK, BELİ BİR AMACA 
UYGUNLUK VE İHLAL ETMEMEYİ İÇEREN HIÇBIR VE HERHANGİ BİR GARANTİ YOKTUR. HİÇBİR DURUM 
ALTINDA, YAZARLAR VEYA TELİF HAKKH SAHİPLERİ, YAZILIMDAN KAYNAKLANAN VEYA İLGİLİ VEYA 
KULLANIMDAKI VEYA DİĞER IŞLEMLERDE ORTAYA ÇIKAN HERHANGI BİR İDDİA, HASAR VEYA DİĞER 
YÜKÜMLÜLÜKLERDEN SORUMLU OLMAYACAKLARDIR.

📈 Yol Haritası

Yaklaşan Özellikler

• 🔄 Geliştirilmiş anahtar kelime araştırması - rakip analizi ile
• 📊 Yerleşik veri görselleştirme - grafikler ve tablolar ile
• 🤖 Yapay zeka destekli optimizasyon önerileri
• 📝 Kampanya oluşturma ve yönetim araçları
• 🔍 Gelişmiş raporlama yetenekleri
• 🌐 Çok dil desteği

---

MCP topluluğu için ❤️ ile yapılmış

Google Ads verilerinizi doğrudan AI asistanlara bağlayın ve doğal dil konuşmaları aracılığıyla güçlü reklam içgörülerini açığa çıkarın.