Maps Lead Scorer

Extension Chrome (Manifest V3) untuk pemakaian pribadi. Di halaman hasil pencarian Google Maps, extension ini membaca kartu bisnis yang sedang tampil, memberi skor 0–100 sebagai calon pelanggan, lalu menampilkannya di panel yang bisa difilter, diurutkan, dan diekspor ke CSV.

Tidak terikat niche: cari "klinik kecantikan Bandung", "klinik gigi Surabaya", "bengkel Bekasi", atau apa pun.

Pasang

1. Buka chrome://extensions di Chrome.

2. Nyalakan Developer mode (kanan atas).

3. Klik Load unpacked, pilih folder hasil clone repo ini (folder yang berisi manifest.json).

4. Buka https://www.google.com/maps dan cari sesuatu. Panel "Maps Lead Scorer" muncul di kanan.

Setelah mengubah file, klik ikon reload pada kartu extension di chrome://extensions, lalu muat ulang tab Maps.

Related MCP server: Google Maps MCP Server

Cara pakai

1. Cari kategori bisnis + kota di Google Maps.

2. Panel otomatis memindai kartu yang tampil. Scroll daftar hasil untuk memuat kartu baru; kartu baru ikut dipindai. Tombol Scan hasil memindai ulang secara manual.

3. Kartu di daftar hasil biasanya tidak menampilkan website dan telepon. Lead seperti itu ditandai data belum lengkap dan kolomnya berisi ?. Klik baris di panel (atau kartu di Maps) untuk membuka detail tempat. Website, telepon, dan alamat lengkap terbaca dari panel detail, lalu skor dihitung ulang.

4. Filter: skor minimum, ulasan minimum, "Tanpa website saja", cari nama/kategori. Klik judul kolom untuk mengurutkan.

5. Export CSV mengekspor daftar yang sedang terfilter (UTF-8 dengan BOM, langsung terbuka di Excel).

6. Daftar terkumpul lintas scroll dan pencarian, disimpan di chrome.storage.local. Hapus daftar mengosongkannya.

Skor

Maksimal 100. Label: ≥70 Potensial, 40–69 Lumayan, <40 Rendah.

Field yang tidak ditampilkan halaman dicatat sebagai "belum diketahui", bukan "tidak ada", dan bernilai 0 poin. "Belum punya website" baru dihitung setelah panel detail tempat itu dibuka dan memang tidak ada tautan website.

Bobot dan daftar host media sosial bisa diubah di halaman pengaturan: chrome://extensions → Maps Lead Scorer → Details → Extension options.

Pakai sebagai MCP

Repo ini juga server MCP, jadi agen AI mana pun yang mendukung MCP bisa mencari dan menilai lead sendiri. Server membuka browser sungguhan lewat Playwright, mencari di Google Maps, membuka tiap tempat untuk membaca website dan telepon, lalu memberi skor memakai modul yang sama dengan extension (src/selectors.js, src/extract.js, src/score.js, src/csv.js).

Dua transport: stdio (default, server dijalankan oleh klien) dan Streamable HTTP (--http, untuk server jarak jauh atau VPS).

Baca bagian "Batasan" di bawah dulu. Mode ini adalah pengumpulan data otomatis, dan ketentuan Google membatasinya.

Pasang: stdio

Perlu Node.js 20+. Tambahkan ke konfigurasi mcpServers klien MCP Anda:

{
  "mcpServers": {
    "maps-lead-scorer": {
      "command": "npx",
      "args": ["-y", "github:karuqii9704/maps-lead-scorer"]
    }
  }
}

Dari hasil clone: npm install, lalu pakai "command": "node", "args": ["/path/ke/maps-lead-scorer/mcp/server.js"].

Browser: server memakai Google Chrome yang terpasang. Kalau tidak ada (misalnya di Linux server), server memakai Chromium bawaan Playwright. Unduh sekali:

npx playwright install --with-deps chromium

Pasang: Streamable HTTP

MLS_AUTH_TOKEN=ganti-dengan-token-acak-minimal-16-karakter \
MLS_HOST=0.0.0.0 MLS_PORT=3333 \
node mcp/server.js --http

• Endpoint: http://HOST:3333/mcp (hanya POST, tanpa sesi). GET /healthz untuk cek hidup.

• Klien mengirim header Authorization: Bearer <token>. Contoh konfigurasi klien:

{
  "mcpServers": {
    "maps-lead-scorer": {
      "url": "https://host-anda.example/mcp",
      "headers": { "Authorization": "Bearer ganti-dengan-token-acak-minimal-16-karakter" }
    }
  }
}

• Default bind 127.0.0.1:3333 tanpa token. Jika MLS_HOST bukan loopback, MLS_AUTH_TOKEN wajib (minimal 16 karakter); tanpa itu server menolak start. Token dibandingkan dengan waktu konstan.

• Server tidak membuat TLS. Letakkan di belakang reverse proxy HTTPS (nginx, Caddy) atau jaringan privat; jangan buka token lewat HTTP polos di internet.

• Di mode HTTP, export_csv hanya boleh menulis di dalam MLS_OUTPUT_DIR (atau folder kerja server).

Pasang: VPS Linux

1. Node.js 20+ dan dependency sistem browser:

   git clone https://github.com/karuqii9704/maps-lead-scorer.git /opt/maps-lead-scorer
   cd /opt/maps-lead-scorer
   npm ci --omit=dev
   npx playwright install --with-deps chromium
   sudo apt-get install -y xvfb xauth

2. Jalankan di bawah xvfb-run -a. Chrome headless mendapat tampilan Maps yang lebih ringkas tanpa jumlah ulasan (diamati 2026-11-13), sehingga skor kehilangan poin ulasan. Dengan layar virtual, server mendeteksi DISPLAY dan memakai mode berlayar (headful) otomatis, tanpa memalsukan user agent.

   xvfb-run -a -s "-screen 0 1280x960x24" node mcp/server.js --http

3. Contoh unit systemd /etc/systemd/system/maps-lead-scorer.service (buat user mls, simpan token di /etc/maps-lead-scorer.env dengan izin 600, isi MLS_AUTH_TOKEN=...):

   [Unit]
   Description=Maps Lead Scorer MCP
   After=network.target
   
   [Service]
   User=mls
   WorkingDirectory=/opt/maps-lead-scorer
   EnvironmentFile=/etc/maps-lead-scorer.env
   Environment=MLS_HOST=127.0.0.1 MLS_PORT=3333 MLS_OUTPUT_DIR=/var/lib/maps-lead-scorer
   StateDirectory=maps-lead-scorer
   ExecStart=/usr/bin/xvfb-run -a -s "-screen 0 1280x960x24" /usr/bin/node mcp/server.js --http
   Restart=on-failure
   
   [Install]
   WantedBy=multi-user.target

   Contoh ini bind ke loopback; arahkan reverse proxy HTTPS ke 127.0.0.1:3333. Untuk bind ke antarmuka lain, ubah MLS_HOST (token tetap wajib).

Pasang: Docker

Dockerfile memakai image resmi Playwright (versi di-pin sama dengan playwright di package.json), menambah xvfb, dan menjalankan mode HTTP sebagai user non-root. Tidak ada rahasia di dalam image; token diberikan saat docker run.

docker build -t maps-lead-scorer .
docker run --rm -e MLS_AUTH_TOKEN=ganti-dengan-token-acak-minimal-16-karakter \
  -p 127.0.0.1:3333:3333 -v mls-data:/data maps-lead-scorer

Jika versi playwright di package.json diubah, ubah juga tag image di baris FROM.

Tools

Nama bobot untuk weights sama dengan tabel skor di atas: noWebsite, socialOnly, phone, reviewsHigh, reviewsMid, ratingMid, ratingHigh.

Variabel lingkungan

Perilaku dan batas

• Jeda acak 1,5–3 detik antar scroll dan antar pembukaan tempat. Tidak bisa dikecilkan. Satu tempat memakan sekitar 5–8 detik, jadi 20 hasil dengan detail butuh sekitar 2–3 menit. Atur timeout klien sesuai, atau kecilkan maxResults. Server mengirim notifikasi progress jika klien meminta.

• Maksimal 60 hasil per panggilan. Panggilan paralel diantrekan satu per satu.

• Satu browser dipakai ulang selama server hidup, lalu ditutup saat server berhenti.

• Di mode berlayar, jendela Chrome terbuka selama pencarian. Biarkan terbuka.

• Kalau Google menampilkan CAPTCHA atau halaman "lalu lintas tidak biasa", server berhenti dan mengembalikan error. Server tidak menyelesaikan atau melewati CAPTCHA, tidak memakai plugin stealth, proxy, atau pemalsuan fingerprint. Tunggu, kurangi volume, atau cari manual di browser Anda. IP datacenter (VPS) lebih sering diminta CAPTCHA daripada IP rumahan.

• Halaman persetujuan Google (jika muncul) dijawab dengan menolak yang tidak esensial.

• Hanya data listing bisnis. Nama pengulas dan isi ulasan tidak dibaca.

• Jika berjalan headless, jumlah ulasan hilang. Skor tetap dihitung tanpa poin ulasan, dan hasil memuat peringatan.

Batasan

• Markup Google Maps bisa berubah kapan saja. Semua selector ada di src/selectors.js; kalau panel berhenti membaca data, perbaiki file itu. Selector diverifikasi pada Maps berbahasa Indonesia (hl=id) tanggal 2026-11-11. Pola teks mendukung Indonesia dan Inggris.

• Data hanya apa yang ditampilkan halaman. Extension membaca halaman Maps di browser Anda; ia tidak mengirim request ke Google atau server mana pun, tidak membuka halaman di latar belakang, dan tidak mengunjungi website bisnis. Server MCP berbeda: ia membuka browser sendiri dan memuat halaman Maps atas nama Anda. Keduanya hanya menyimpan data listing bisnis (nama, kategori, rating, jumlah ulasan, telepon, alamat, website). Nama pengulas dan isi ulasan tidak diambil, dan website bisnis tidak dikunjungi.

• Ketentuan Google membatasi pengumpulan data otomatis dari Maps. Extension dimaksudkan untuk prospecting manual dan pribadi dengan kecepatan manusia: Anda sendiri yang mencari, scroll, dan membuka tempat. Mode MCP adalah pengumpulan otomatis, jadi melanggar batasan itu secara langsung; risikonya ada pada Anda. Jaga volume tetap kecil, jangan dijadwalkan atau dijalankan massal, dan jangan menjual ulang data. Google bisa menampilkan CAPTCHA atau memblokir IP Anda kapan saja, dan server ini tidak akan menghindarinya.

• Pembacaan website dan telepon langsung dari kartu daftar hasil belum terverifikasi di Maps live, karena layout yang diperiksa tidak menampilkannya di kartu. Jalur yang terverifikasi adalah lewat panel detail.

• Tempat yang panel detailnya tidak punya alamat, telepon, atau website sama sekali akan tetap berstatus "data belum lengkap".

• Hanya berjalan di https://www.google.com/maps/*. Kalau Maps Anda terbuka di domain lain (misalnya google.co.id), tambahkan polanya ke matches di manifest.json.

• Skor adalah heuristik awal, bukan penilaian kualitas bisnis.

Pengembangan

Extension tidak punya build step dan tidak butuh dependency. Dependency (@modelcontextprotocol/sdk, playwright, zod) hanya untuk server MCP.

npm install
npm test

Test mencakup modul murni dan smoke test MCP offline (tanpa browser, tanpa jaringan). search_leads dan get_place hanya bisa dicoba langsung ke Maps.

• src/selectors.js — selector dan pola teks Maps.

• src/extract.js — kartu / panel detail → data lead (murni, diuji).

• src/score.js — lead + bobot → skor dan alasan (murni, diuji).

• src/csv.js — daftar lead → CSV (murni, diuji).

• src/content.js, src/panel.css — panel di halaman Maps.

• options.html, src/options.js — pengaturan bobot dan host media sosial.

• mcp/server.js — entry server MCP (stdio atau --http).

• mcp/tools.js — definisi tools. mcp/http.js — transport Streamable HTTP dan auth.

• mcp/browser.js — Playwright: buka Maps, scroll, suntik src/selectors.js + src/extract.js ke halaman.

• test/ — fixture HTML, DOM mini untuk Node, dan test.

Lisensi

MIT. Lihat LICENSE.