Cara Membangun MCP Google Analytics di Localhost untuk Cursor dan VS Code

Membangun MCP Google Analytics di artikel ini berarti menyiapkan server resmi Google (analytics-mcp versi 0.7.0) di mesin Anda, mengautentikasi akses baca GA4, lalu menghubungkannya ke agent di Cursor atau VS Code. Fokusnya deploy engine first-party lewat transport stdio agar agent memanggil tool API alih-alih menebak angka, tanpa implementasi protokol MCP dari nol.

Alur kerja artikel ini: prasyarat cloud dan GA4, instalasi Python lokal, validasi berlapis, konfigurasi IDE, lalu prompt yang memicu run_report dan tool terkait dengan parameter eksplisit. Server upstream masih berstatus Experimental (Development Status Beta di metadata PyPI). Namun nama tool atau respons API dapat berubah antar rilis minor.

Model Context Protocol dan Google Analytics MCP

Model Context Protocol adalah protokol terbuka berbasis JSON-RPC yang memungkinkan aplikasi client (chat agent di IDE) memanggil tools pada server eksternal. Jadi analoginya colokan standar antara agent dan data operasional, bukan model AI baru.

Pada transport stdio, IDE meluncurkan server MCP sebagai subprocess. Pesan protokol valid hanya lewat stdout. Log debug engine resmi Google boleh ke stderr sehingga stderr aman dibaca developer saat diagnosis, tanpa mengganggu handshake MCP. Jangan menjalankan analytics-mcp.exe di terminal interaktif lalu mengharapkan output laporan yang mudah dibaca manusia, karena itu bukan jalur konsumsi data. Client IDE yang benar akan mem-parse stdout sebagai JSON-RPC MCP, lalu menampilkan hasil tool ke chat agent.

Google Analytics MCP (google-analytics-mcp di GitHub) adalah server first-party yang membungkus Google Analytics Admin API dan Google Analytics Data API. Paket PyPI analytics-mcp 0.7.0 membutuhkan Python 3.10 hingga 3.13. Server ini berbeda dari dashboard GA4, Looker Studio, export BigQuery, atau MCP SEO pihak ketiga yang menggabungkan Search Console dan vendor keyword.

Untuk gambaran ekosistem MCP yang lebih luas (termasuk posisi GA4 di antara crawl dan keyword tools), lihat katalog MCP SEO di blog CodeF. Artikel ini hanya depth setup GA4 resmi Google, bukan duplikasi daftar puluhan server.

Manfaat Setup MCP Google Analytics di Mesin Sendiri

Masalah yang sering muncul tanpa MCP: metrik disalin manual ke chat, periode dibandingkan tanpa parameter konsisten, dan agent cenderung mengisi angka bila tidak ada sumber API. Dengan MCP GA4, agent memanggil run_report dengan property_id, rentang tanggal, metrik, dan dimensi yang Anda minta. Bila API gagal, agent melaporkan error apa adanya, bukan angka rekaan. Parameter tercatat di log tool sehingga laporan mingguan bisa diulang dengan prompt yang sama.

Kredensial Service Account tetap di folder lokal (secrets/) asalkan Anda tidak mengunggah JSON ke Git atau chat. Satu akun Viewer di level GA4 Account sering cukup untuk multi-properti: agent memetakan nama tampilan ke Property ID lewat get_account_summaries. Mode baca default mengurangi risiko mengubah properti GA4 lewat otomasi. Tim agency yang mengelola banyak brand domain dapat satu kali setup MCP lalu memilih properti lewat nama tampilan, tanpa menukar file kredensial setiap kali berganti klien uji.

Prasyarat MCP Google Analytics: GCP, GA4, dan IDE

Sebelum instalasi, pastikan empat lapisan siap: runtime Python, API Google Cloud, izin GA4, dan IDE dengan dukungan MCP agent. Lewat satu lapisan saja cukup untuk error 401 atau handshake MCP yang terlihat sehat tetapi tool laporan gagal diam-diam.

• Python 3.10, 3.11, 3.12, atau 3.13 sesuai metadata upstream.
• Proyek Google Cloud dengan Analytics Admin API dan Analytics Data API aktif. Mengaktifkan API di GCP tidak otomatis memberi akses data GA4.
• Service Account dengan file JSON key. Google menyarankan meminimalkan key jangka panjang. Rotasi key dan folder secrets/ di .gitignore wajib menjadi kebiasaan.
• Email Service Account ditambahkan di GA4 Admin → Account access management (disarankan untuk multi-properti) atau Property access dengan role Viewer. Panduan peran ada di dokumentasi access management GA4.
• Property GA4 uji dengan Measurement ID G-... terpisah dari Property ID numerik yang dipakai Data API.
• Cursor dengan MCP project/global, atau VS Code dengan GitHub Copilot agent mode dan dukungan MCP (dokumentasi MCP VS Code).

Tutorial berikut memakai Windows dan PowerShell dengan path generik C:/Projects/mcp-ga4-example. Di macOS atau Linux, ganti path venv ke bin/analytics-mcp dan pemisah path sesuai OS.

Sembilan Tool analytics-mcp 0.7.0

Engine 0.7.0 mendaftarkan sembilan tool. Akhirnya, prompt agent harus selaras dengan parameter masing-masing tool, terutama laporan historis dan konversi.

Konsep laporan Data API mengikuti quickstart Reporting Data API. Bedakan activeUsers, totalUsers, sessions, dan metrik engagement saat meminta interpretasi agent.

Langkah Membangun MCP Google Analytics di Localhost

Ada dua pendekatan valid: scaffold proyek dengan venv (diutamakan di artikel ini) atau menjalankan paket upstream lewat pipx run analytics-mcp seperti README Google. Pilih salah satu, tidak perlu keduanya sekaligus. Setelah engine terpasang, baru sambungkan IDE.

Siapkan proyek dan Service Account

Buat folder C:/Projects/mcp-ga4-example. Salin template dari README upstream (struktur minimal: venv, skrip setup, file contoh env). Instal paket dengan pin versi:

cd C:\Projects\mcp-ga4-example
python -m venv .venv
.\.venv\Scripts\pip install analytics-mcp==0.7.0

Di Google Cloud Console, buat proyek atau pilih proyek existing, aktifkan Analytics Admin API dan Analytics Data API di Library, lalu buat Service Account dengan role minimal yang diperlukan untuk menjalankan client API. Unduh JSON key ke secrets/ga4-service-account.json. Jangan menempel isi key ke chat agent. Di GA4, buka Admin → Account access management, tambahkan email Service Account dengan role Viewer. Untuk properti uji example.com, catat Property ID numerik di Admin → Property settings. Salin .env.example menjadi .env dengan placeholder berikut (nilai contoh, bukan produksi):

GOOGLE_APPLICATION_CREDENTIALS=C:/Projects/mcp-ga4-example/secrets/ga4-service-account.json
GOOGLE_PROJECT_ID=your-gcp-project-id
GA_PROPERTY_ID=123456789

Angka 123456789 hanya ilustrasi untuk properti fiktif example.com. Property ID nyata Anda diambil dari GA4 Admin atau dari output get_account_summaries, bukan dari tag G- di situs.

Validasi berlapis sebelum IDE

Scaffold tutorial sering menyediakan skrip verifikasi tiga tahap: struktur env dan JSON tanpa jaringan, token plus panggilan API live, lalu handshake MCP dan daftar tool. Kegagalan awal biasanya path atau format JSON. Meski handshake MCP sudah hijau, error 401 atau 403 pada uji live mengarah ke Viewer GA4 atau API GCP yang belum aktif.

Alternatif resmi Google: set variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS dan GOOGLE_PROJECT_ID, lalu jalankan pipx run analytics-mcp sesuai README repositori. Prinsip autentikasi sama.

Integrasi MCP Google Analytics di Cursor

Cursor membaca konfigurasi MCP per proyek di .cursor/mcp.json. Contoh generik server stdio:

{
  "mcpServers": {
    "analytics-ga4-local": {
      "type": "stdio",
      "command": "C:/Projects/mcp-ga4-example/.venv/Scripts/analytics-mcp.exe",
      "args": [],
      "envFile": "C:/Projects/mcp-ga4-example/.env"
    }
  }
}

Buka folder proyek sebagai workspace, lalu refresh daftar MCP di pengaturan Cursor (dokumentasi MCP Cursor). Label menu dapat berbeda antarversi IDE. Kemudian uji prompt singkat yang memanggil get_account_summaries.

Untuk MCP aktif di banyak repo, salin entri serupa ke %USERPROFILE%\.cursor\mcp.json. Di Windows, path executable yang mengandung spasi dapat memecah parsing: mitigasi umum memakai path 8.3 ke .exe atau memindahkan venv ke folder tanpa spasi. Path penuh pada envFile umumnya lebih toleran.

Rules, skills, atau slash command analisis GA4 (/mcp-ga, /mcp-ga-laporan, dan sejenisnya) adalah perluasan scaffold Cursor opsional, bukan bagian paket PyPI Google. VS Code tidak memiliki paritas slash command tersebut.

Integrasi MCP GA4 di VS Code Copilot

Aktifkan agent mode di Copilot Chat. Konfigurasi workspace memakai .vscode/mcp.json dengan kunci servers, bukan selalu mcpServers ala Cursor:

{
  "inputs": [],
  "servers": {
    "analytics-ga4-local": {
      "type": "stdio",
      "command": "C:/Projects/mcp-ga4-example/.venv/Scripts/analytics-mcp.exe",
      "args": [],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "C:/Projects/mcp-ga4-example/secrets/ga4-service-account.json",
        "GOOGLE_PROJECT_ID": "your-gcp-project-id"
      }
    }
  }
}

Gunakan perintah palet MCP: Add Server dan MCP: List Servers, lalu refresh tools di Chat. Sedangkan prompt harus natural language: sebut server analytics-ga4-local dan minta pemanggilan tool eksplisit.

Prompt Agent Saat Fase Setup

Tempel prompt berikut ke Cursor Agent saat memeriksa konfigurasi, bukan saat meminta laporan traffic. Prompt setup sengaja meminta agent memverifikasi path, venv, dan handshake MCP tanpa mengekspor private key JSON ke chat.

Saya menyiapkan MCP Google Analytics resmi (analytics-mcp 0.7.0) di Windows.
Folder proyek: C:/Projects/mcp-ga4-example
Bantu saya memeriksa: Python 3.10+, venv, file .env (GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_PROJECT_ID, GA_PROPERTY_ID), dan .cursor/mcp.json stdio ke analytics-mcp.exe.
Jangan cetak isi private key JSON. Jika tes API gagal, jelaskan langkah 401/403/404 berdasarkan error saja.

Jalankan urutan diagnostik: verify offline, verify live, check MCP handshake.
Laporkan apakah tool run_report terdaftar. Property uji: example.com (Property ID numerik dari get_account_summaries, jangan mengarang angka).

Untuk VS Code Copilot, gunakan prompt paralel yang meminta draf .vscode/mcp.json dan langkah refresh tools tanpa secret di chat:

Proyek MCP GA4 di C:/Projects/mcp-ga4-example. Buatkan draf .vscode/mcp.json untuk Copilot agent mode: server stdio analytics-ga4-local, env GOOGLE_APPLICATION_CREDENTIALS dan GOOGLE_PROJECT_ID.
Jangan masukkan secret ke chat. Setelah config, jelaskan cara MCP: List Servers dan refresh tools di Chat.

Prompt Harian: Laporan dan Realtime

Setelah status server connected di IDE, minta agent memanggil tool, bukan menebak analytics. Walau Property ID sudah ada di .env, tetap valid memulai dari get_account_summaries bila Anda bekerja dengan banyak properti uji seperti example.com atau example.net. Blok di bawah adalah contoh bahasa natural yang memicu tool dengan parameter eksplisit.

Contoh prompt Cursor untuk laporan mingguan, banding periode, device brand, dan realtime:

Pakai MCP GA4. Untuk properti yang namanya mengandung example.com, tampilkan activeUsers dan sessions untuk tujuh hari kalender lengkap terakhir. Sebut Property ID, rentang tanggal, dan timezone properti. Jangan mengarang angka jika API gagal.

Compare traffic example.com: minggu ini vs minggu lalu (dua date range). Metrik: activeUsers, sessions, engagementRate. Tabel ringkas plus interpretasi non-spesulatif.

Dari GA4 MCP, device brand untuk example.com 7 hari terakhir. Top 10 deviceBrand by activeUsers.

run_realtime_report untuk example.com: activeUsers sekarang. Jika dimensi channelGrouping tidak valid di realtime, jelaskan batas API.

Contoh paralel VS Code yang menyebut server by name:

@workspace Gunakan server MCP analytics-ga4-local. Panggil get_account_summaries, lalu run_report untuk properti example.com: activeUsers dan sessions, date range 7 hari terakhir.

Tabel berikut membantu Anda merumus prompt tanpa menebak nama tool internal. Sesuaikan domain uji dengan properti yang benar-benar ada di akun GA4 Anda.

Aturan pelaporan untuk agent: sebut property_id, date range, metrics, dimensions, dan filters. Bandingkan periode dengan timezone properti dan hari kalender penuh. Saat traffic anomali, bandingkan dengan periode serupa sebelum menyimpulkan bot. Untuk hygiene data bot di GA4, workflow GTM dan edge filter dijelaskan terpisah pada tutorial menyaring traffic bot GA4.

Troubleshooting MCP Google Analytics dan API

Jika live test sukses tetapi metrik nol, cek implementasi measurement di website. Lantaran MCP hanya membaca API, dashboard kosong sering berasal dari tag GA4, bukan dari handshake IDE. Panduan gejala dashboard kosong ada di artikel Google Analytics kosong. Jangan menyarankan scope tulis atau flag --allow-write kecuali artikel terpisah membahas risiko edit properti.

FAQ Setup MCP GA4

Service Account atau OAuth user? Artikel ini fokus Service Account untuk otomasi lokal. OAuth user dapat didukung upstream, lihat README GitHub bila alur login interaktif lebih cocok. pipx atau venv? Keduanya valid. venv plus skrip verify mempermudah Windows dan tim yang ingin repo reproducible.

Multi-properti? Viewer di GA4 Account plus get_account_summaries memetakan nama properti ke ID numerik sebelum run_report. Apakah MCP menggantikan Search Console atau Ahrefs? Tidak. Server ini hanya GA4 Admin dan Data API. Stack data SEO multi-sumber dibahas di hub MCP SEO, bukan di sini.

Langkah Setelah Localhost Terhubung

Simpan prompt laporan mingguan yang sudah teruji, dokumentasikan Property ID per domain uji, dan pantau changelog analytics-mcp karena status Experimental. OAuth versus rotasi key Service Account masuk rutinitas keamanan berkala.

Bila Anda butuh integrasi GA4 dengan WordPress, audit tracking, atau workflow agent yang menggabungkan analytics dengan SEO teknis, tim CodeF dapat membantu merapikan measurement, akses API, dan konfigurasi agent tanpa mengekspos kredensial ke cloud publik. Konsultasi tetap opsional setelah Anda memahami alur localhost di atas.