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.

Dukungan dan sumber daya komunitas

Ringkasan teknis

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

Spesifikasi utama

  • Protokol: MCP (Model Context Protocol)
  • Mode: Hanya baca (rilis saat ini)
  • Bahasa: Python
  • Transportasi: Input/output standar (stdio)
  • 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 membuat kueri Google Ads API.
  4. Penyisipan konteks: Hasil terstruktur ditampilkan ke jendela konteks LLM.
  5. Respons: LLM menyintesis 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 Developer Google Ads:

  • Token developer: String akses 22 karakter unik Anda.
  • Project ID: ID project Google Cloud Anda.
  • Kredensial OAuth: Pasangan Client ID/Rahasia klien OAuth2, atau serangkaian kredensial default aplikasi.

Konfigurasi

Untuk mengintegrasikan server ke host yang kompatibel dengan MCP, tambahkan entri berikut ke file konfigurasi MCP host Anda, seperti settings.json. Lihat dokumentasi host Anda untuk mengetahui lokasi dan nama file konfigurasi ini yang tepat.

JSON

{
  "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_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
      }
    }
  }
}

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 terinstal, diautentikasi, dan project aktif 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. 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.

Deploy ke Google Cloud Run

Pastikan untuk menyetel variabel lingkungan yang diperlukan:

  • GOOGLE_PROJECT_ID: ID project Google Cloud Anda.
  • GOOGLE_ADS_DEVELOPER_TOKEN: Token developer yang ingin Anda gunakan oleh server MCP.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Client ID OAuth yang ingin digunakan server MCP.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Rahasia Klien OAuth yang ingin digunakan server MCP.
  • GOOGLE_ADS_MCP_BASE_URL: URL dasar tempat server MCP Anda dapat diakses: URL ini akan otomatis ditetapkan oleh Google Cloud Run setelah deployment pertama Anda. Anda dapat mengupdate variabel lingkungan setelah deployment.
  • FASTMCP_HOST: Setel ini ke 0.0.0.0 agar FastMCP dapat menerima koneksi dari semua alamat IP.
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_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,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"

Mengonfigurasi klien MCP

Setelah deployment, perbarui konfigurasi klien MCP (misalnya, ~/.gemini/settings.json) untuk menggunakan URL Cloud Run.

{
  "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 "kampanye".

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

Contoh perintah untuk memulai

Tanyakan apa yang dapat dilakukan server:

What can the google-ads-mcp server do?

Tanyakan tentang pelanggan:

What customers do I have access to?

Tanyakan 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