Server MCP Google Ads: Panduan integrasi developer

Model Context Protocol (MCP) adalah standar terbuka yang memungkinkan Model Bahasa Besar (LLM) berinteraksi dengan 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 referensi komunitas

Ringkasan teknis

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

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 menyusun data menjadi jawaban yang dapat dibaca manusia.

Mulai

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

Prasyarat

Sebelum 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. 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"
      }
    }
  }
}

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 di berbagai agen atau menjalankannya sebagai layanan web.

Prasyarat

  1. Project Google Cloud.

  2. Alat command line gcloud diinstal, diautentikasi, dan dengan project aktif yang 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 kirim image:

    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: 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 Anda gunakan oleh 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: Tetapkan nilai 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, update konfigurasi klien MCP Anda (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: Menjalankan Google Ads Query Language (GAQL) permintaan 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 saja 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