Server MCP Google Ads: Panduan integrasi developer

Model Context Protocol (MCP) adalah standar terbuka yang memungkinkan Model Bahasa Besar (LLM) berinteraksi secara aman dengan data dan aplikasi eksternal. Server MCP Google Ads menyediakan jembatan standar ke Google Ads API, yang memungkinkan agen AI menganalisis dan mengambil data kampanye menggunakan bahasa alami.

Referensi dan dukungan komunitas

Ringkasan teknis

Dengan menerapkan server MCP ini, Anda tidak perlu menulis "kode penghubung" kustom untuk autentikasi Google Ads API, pengambilan resource, dan penguraian data. Server mengekspos alat tertentu yang dapat ditemukan dan dipanggil oleh LLM secara mandiri.

Spesifikasi utama

  • Protokol: MCP (Model Context Protocol)
  • Mode: Hanya baca (rilis saat ini)
  • Bahasa: Python
  • Transport: Input/output standar (stdio) atau HTTP yang Dapat Di-stream (streamable-http / Cloud Run)
  • Autentikasi: OAuth 2.0 atau akun layanan

Cara kerja loop interaksi

  1. Permintaan: Pengguna mengirimkan kueri seperti "Bagaimana performa kampanye saya minggu ini?".
  2. Penemuan: LLM memeriksa alat yang tersedia dan mengidentifikasi kemampuan penelusuran google-ads-mcp.
  3. Eksekusi: Server MCP menjalankan logika Python yang mendasarinya untuk mengkueri Google Ads API.
  4. Injeksi konteks: Hasil terstruktur ditampilkan ke jendela konteks LLM.
  5. Respons: LLM menyusun data menjadi jawaban yang dapat dibaca manusia.

Mulai

Ikuti langkah-langkah berikut untuk mengonfigurasi dan menggunakan server MCP Google Ads.

Prasyarat

Sebelum melakukan konfigurasi, pastikan Anda memiliki kredensial berikut dari konsol Google Cloud:

Konfigurasi

Untuk mengintegrasikan server ke host yang kompatibel dengan MCP, tambahkan entri berikut ke file konfigurasi MCP host Anda, seperti settings.json, dan arahkan GOOGLE_APPLICATION_CREDENTIALS ke file JSON ADC Anda (atau konfigurasi ADC default dengan gcloud auth application-default login). Jika Anda mengakses akun melalui akun pengelola, Anda juga dapat menyetel GOOGLE_ADS_LOGIN_CUSTOMER_ID. Lihat dokumentasi host Anda untuk mengetahui lokasi dan nama file yang tepat dari konfigurasi ini.

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

Deployment di Google Cloud

Daripada menghosting server MCP ini secara lokal, Anda dapat menghostingnya di Google Cloud Run atau di infrastruktur berbasis cloud lainnya. Hal ini berguna jika Anda ingin membagikan server ke berbagai agen atau menjalankannya sebagai layanan web.

Prasyarat

  1. Project Google Cloud.

  2. Alat command line gcloud telah diinstal, diautentikasi, dan project aktif telah dikonfigurasi:

    gcloud config set project YOUR_PROJECT_ID

Membangun dan mengirim image Docker

Anda dapat menggunakan Cloud Build untuk membangun dan mengirim image ke Artifact Registry tanpa perlu menginstal Docker secara lokal.

  1. Buat repositori di Artifact Registry:

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

  2. Buka direktori project:

    cd <full path>/google-ads-mcp

  3. Buat dan kirimkan gambar:

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

    Perhatikan bahwa langkah ini harus dilakukan setiap kali Anda ingin mengupdate server yang di-deploy ke versi terbaru.

Men-deploy ke Google Cloud Run

Pastikan untuk menetapkan variabel lingkungan yang diperlukan:

  • GOOGLE_PROJECT_ID: Project ID Google Cloud Anda, yang memiliki tingkat akses API yang sesuai.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Client ID OAuth 2.0 (dikonfigurasi sebagai Aplikasi web di project Google Cloud Anda) untuk autentikasi OAuth tingkat aplikasi. Pastikan bahwa:
    • Anda telah menambahkan URI pengalihan yang diberi otorisasi yang sesuai untuk klien AI yang ingin Anda hubungkan (seperti https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect, atau https://antigravity.google/oauth-callback).
    • Anda telah menambahkan cakupan https://www.googleapis.com/auth/adwords ke layar izin OAuth di bagian APIs & Services > OAuth consent screen > Data Access (Add or remove scopes).
    • Jika status publikasi layar izin OAuth Anda ditetapkan ke Testing (default), Anda telah menambahkan Akun Google yang terhubung ke server MCP sebagai Test users di bagian APIs & Services > OAuth consent screen > Audience (Test users > + Add users).
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Rahasia Klien OAuth yang sesuai dengan Client ID OAuth.
  • GOOGLE_ADS_MCP_BASE_URL: URL dasar publik tempat server MCP Anda dapat diakses (misalnya, https://google-ads-mcp-xyz-uc.a.run.app). Karena Google Cloud Run membuat URL ini selama deployment awal, deploy tanpa variabel ini terlebih dahulu, lalu update layanan setelah deployment.
  • FASTMCP_HOST: Tetapkan ke 0.0.0.0 untuk mengizinkan FastMCP menerima koneksi dari semua alamat IP.

Deploy layanan ke Google Cloud Run:

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"

Setelah Cloud Run menyelesaikan deployment, ambil URL layanan yang ditetapkan dan perbarui layanan dengan variabel lingkungan GOOGLE_ADS_MCP_BASE_URL:

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"

Model autentikasi dan keamanan

Men-deploy dengan --allow-unauthenticated akan menonaktifkan pemeriksaan IAM tingkat infrastruktur Cloud Run (roles/run.invoker) sehingga klien AI eksternal dapat terhubung tanpa memerlukan token akun layanan Google Cloud. Autentikasi didelegasikan ke lapisan aplikasi:

  • Jika GOOGLE_ADS_MCP_OAUTH_CLIENT_ID dan GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET diberikan, server MCP akan menerapkan Google OAuth 2.0 pada semua permintaan masuk, sehingga menantang pemanggil yang tidak diautentikasi dengan respons HTTP 401. Semua permintaan alat dijalankan secara ketat berdasarkan identitas OAuth pemanggil yang diautentikasi.
  • Menghilangkan --allow-unauthenticated akan menerapkan IAM infrastruktur Cloud Run, yang mengharuskan pemanggil meneruskan token identitas OIDC Google Cloud dengan setiap permintaan. Karena klien AI standar (seperti Claude dan ChatGPT) melakukan autentikasi menggunakan OAuth pengguna akhir, bukan token identitas Google Cloud IAM, koneksi langsung dari platform ini memerlukan --allow-unauthenticated dengan OAuth level aplikasi.

Mengonfigurasi klien MCP

Setelah deployment, konfigurasi klien MCP Anda dengan URL Cloud Run. Karena server memerlukan autentikasi OAuth 2.0, klien harus mendukung alur OAuth MCP atau menyediakan token pemilik yang diotorisasi:

  • Klien yang mendukung OAuth: Untuk klien yang mendukung penemuan OAuth MCP (seperti Antigravity), menghubungkan ke endpoint akan memicu perintah autentikasi untuk login dengan Google dan memberikan cakupan https://www.googleapis.com/auth/adwords (tercantum sebagai .../auth/adwords di Konsol Google Cloud).
  • Platform AI pihak ketiga (Claude, ChatGPT): Di setelan konektor atau integrasi klien, tambahkan konektor kustom yang mengarah ke URL Cloud Run dengan jalur /mcp (misalnya, https://your-cloud-run-url.a.run.app/mcp), pilih autentikasi OAuth 2.0 (menggunakan Client ID dan Rahasia klien OAuth Anda sendiri), dan pastikan URI callback klien ditambahkan ke URI pengalihan yang diizinkan klien OAuth Anda. (Peserta yang masuk dalam daftar yang diizinkan untuk uji coba endpoint yang dihosting juga dapat melihat panduan penyiapan MCP yang dihosting.)
  • Klien tanpa dukungan OAuth: Klien yang tidak mendukung alur OAuth HTTP akan menerima respons HTTP 401 Unauthorized. Untuk alat ini, gunakan konfigurasi stdio lokal.

Contoh konfigurasi untuk klien yang mendukung OAuth (misalnya, ~/.gemini/settings.json):

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

Kemampuan inti (alat)

Server ini mengekspos alat yang dirancang untuk penemuan akun dan pelaporan performa:

  • list_accessible_customers: Menampilkan daftar ID pelanggan Google Ads dan nama akun yang dapat diakses oleh pengguna yang diautentikasi.
  • search: Mengeksekusi permintaan Google Ads Query Language (GAQL) untuk mengambil metrik, anggaran, dan status resource.

  • get_resource_metadata: Mengambil metadata tentang jenis resource Google Ads API, misalnya "campaign".

    Hal ini berguna untuk memahami struktur data dan kolom yang tersedia untuk kueri.

Contoh perintah untuk memulai

Tanyakan apa yang dapat dilakukan server:

What can the google-ads-mcp server do?

Bertanya tentang pelanggan:

What customers do I have access to?

Bertanya tentang kampanye:

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