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) atau HTTP/SSE (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 pokok untuk membuat kueri Google Ads API.
  4. Penyisipan 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.

Deploy ke Google Cloud Run

Pastikan untuk menetapkan variabel lingkungan yang diperlukan:

  • GOOGLE_PROJECT_ID: ID project Google Cloud Anda, yang memiliki tingkat akses API yang sesuai.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Client ID OAuth yang ingin Anda gunakan oleh 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 ditetapkan secara otomatis oleh Google Cloud Run setelah deployment pertama Anda. Anda dapat mengupdate variabel lingkungan setelah deployment.
  • FASTMCP_HOST: Tetapkan 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_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 "campaign".

    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?

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