🗺️ Gmap-Business-Agent

A Google Maps scraper that runs as an MCP server — letting Claude search, extract, and save business data through natural conversation instead of terminal commands.

---

💥 The Problem

Most scraping tools are one-shot scripts. You run them, they finish, they close. If something breaks mid-run, you find out after the fact — usually with no idea what failed or why.

Google Maps makes this worse. It loads content dynamically, detects automation patterns, and silently returns incomplete data without throwing errors. A naive scraper either crashes or returns garbage with no indication which one happened.

The result is a tool you can't trust — and data you can't rely on.

---

🎯 What this does

Gmap Business Agent wraps a production-grade Playwright scraper inside an MCP server, exposing two tools Claude can call directly from conversation:

• scrape_google_maps — search and return structured business data
• scrape_and_save — search, extract, and export to xlsx or csv

Instead of running a terminal command with flags, you tell Claude what you need. Claude calls the right tool, the scraper runs, and results come back structured and ready to use.

Each result contains: name, category, rating, contact, address, website, link

---

🗺️ How it works

Claude (MCP Client)
      ↓
  MCP Server  ←  server.py
      ↓
  Scrape orchestrator  ←  core/scrape.py
      ↓
  ┌──────────────┬──────────────┐
  │ map_search   │  get_links   │
  │ core/        │  core/       │
  └──────┬───────┴──────┬───────┘
         │              │
         └──── get_data ┘
               core/
                 ↓
           save_file  ←  utils/

The scraper handles two cases automatically:

• /place/ URL → single result detected, data extracted directly
• /search/ URL → multiple results, links collected first then visited one by one

---

⚙️ Execution model

The scraper supports two execution modes:

1. Persistent MCP server (production

When a tool is called:

• Playwright launches a browser with automation flags disabled and a real user agent
• Google Maps is searched and the redirect URL is inspected to determine single vs multiple results
• For multiple results, the feed panel is scrolled using JavaScript against the virtual DOM — not a raw pixel wheel event
• Each place link is visited, data extracted via a centralized fallback function that logs missing fields instead of crashing
• Results are returned as structured dictionaries, optionally saved to file

2. Standalone CLI script (manual testing)

• Run python main.py from the terminal.
• Follows the same scraping logic but saves results to CSV/XLSX and prints them to console.
• Useful for debugging, one‑off scraping, or when MCP is not available.

Every action is logged. Every failure is visible. No silent data loss.

---

🛡️ Anti-bot handling

Google Maps detects automation patterns and silently degrades results. This project handles that at the browser level:

• --disable-blink-features=AutomationControlled removes the automation flag from the browser
• Real user agent and locale mimics a normal Chrome session
• JavaScript scroll on the virtual DOM feed panel instead of raw mouse wheel
• wait_for_selector and wait_for_load_state instead of hardcoded timeouts
• Centralized fallback on missing elements — no crashes, no skipped records without logging

---

⚠️ Known Limitations

• Proxy rotation not included — for high-volume scraping, residential proxies are recommended as a separate layer
• CAPTCHA solving not handled — graceful detection only, no automatic resolution
• Speed is bound by Google Maps response time, not the scraper itself
• Single browser instance — concurrent scraping not supported in current version
• Selectors are tied to Google Maps current DOM structure — layout changes may require updates

---

▶️ How to run

Requirements

• Python 3.10+
• uv as project manager — install here
• Claude Desktop with MCP support enabled

Install

uv sync

Connect to Claude Desktop

Add this to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "gmap-agent": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/path/to/this/project"
    }
  }
}

Use from Claude

Search for coffee shops in Indonesia, get 15 results

Find hospitals in Malaysia and save to csv

---

📚 Libraries

• playwright — browser automation and anti-detection handling
• fastmcp — MCP server framework, tool registration and stdio transport
• pandas — structured data export to xlsx and csv
• python-dotenv — configuration via environment variables