Google Maps Scraper Kit

A free, local Google Maps scraper and Claude Code skill for lead generation. Name a business type and a city. Get back a clean, outreach-ready CSV: name, phone, email, website, category, address, rating, and review count. Optional Instagram, Facebook, and LinkedIn enrichment.

Everything runs on your machine. No SaaS, no credits, no API keys.

---

Why it exists

Ask a chat AI to "scrape Google Maps" and it hits a consent wall and JavaScript-rendered pages. Result: close to zero structured rows. This kit runs a real headless scraping engine locally and gives Claude a precise operating manual for it. Result: dozens to hundreds of verified listings per query.

Capabilities

Lead-ready output	The engine captures ~34 raw fields. The kit keeps the 8 you contact and qualify with, and writes a CSV. --full keeps everything.
Email extraction	On by default. Pulls contact emails from each business website.
Social enrichment	--socials finds Instagram, Facebook, and LinkedIn profiles. Runs in code (HTTP + regex), zero AI tokens.
Auto-geocoding	Type a city name. Coordinates are resolved for you.
Batch jobs	Many keywords, one job, one CSV.
Claude-native	A skill plus four slash commands. Claude handles create, poll, download, clean, and present.
Safe defaults	API bound to 127.0.0.1, secrets git-ignored, rate-limit and data-law guardrails built into the skill.

---

Quick start

Requires Docker Desktop. Python 3 is optional (standard library only).

git clone https://github.com/Mahanaicoach/google-maps-scraper-kit.git
cd google-maps-scraper-kit
docker compose up -d

./scripts/scrape.sh "coffee shops in Austin TX" 30.2672 -97.7431 5

Or open the folder in Claude Code and say:

Scrape gyms in Miami and give me phones and websites.

Example output

coffee_shops_austin.csv (illustrative rows):

title	phone	emails	website	category	address	review_rating	review_count
Example Roasters	+1 512-555-0101	hello@example.com	example.com	Coffee shop	100 Congress Ave, Austin, TX	4.7	812
Sample Espresso Bar	+1 512-555-0102	info@example.org	example.org	Cafe	200 S Lamar Blvd, Austin, TX	4.5	356

Add --socials for instagram, facebook and linkedin columns, or --full for all ~34 raw fields.

Detailed setup: SETUP.md. Skill reference: SKILL.md.

---

Using it in Claude Code

Command	Action
/scrape <business> in <city, ST> [depth]	Run one scrape, return a clean table and CSV
/scrape-batch <keywords-file> [--city "City, ST"]	Run many queries as one job
/scrape-setup	Start the engine and run a health check
/scrape-jobs [list | delete <id>]	List or delete jobs

Plain language works too. The skill triggers on requests like "build me a lead list of dentists in Denver, CO" or "pull Google Maps listings for plumbers in Phoenix". It does not scrape social platforms directly.

Without Claude

scripts/scrape.py is a standalone, dependency-free Python CLI: single queries, batches, geocoding, socials, CSV output. scripts/scrape.sh covers the single-query case in bash.

---

Responsible use

This drives a real scraper against Google Maps. Light use is fine. Heavy use without proxies can get your IP temporarily rate-limited (minutes to hours). Your Google account is not affected.

• Run one job at a time. Start at depth 5 and raise only when needed.
• Watch for block signals: failed jobs, empty results, or far fewer rows than an identical earlier run.
• Add proxies for large or repeated runs. The engine rotates them automatically:

  "proxies": ["socks5://user:pass@host:port", "http://host2:port2"]
  

  Supported: socks5, socks5h, http, https.
• Scraping Maps is against Google's Terms of Service. Treat output as leads to verify, not a dataset to resell. Phones and emails are personal data: follow GDPR, CCPA, and CAN-SPAM.

For large requests, Claude flags the risk and suggests proxies, then proceeds. It refuses only clearly abusive use.

---

How it compares

	This kit	Asking a chat AI	Paid cloud scrapers	Copying by hand
Cost	Free (MIT)	Free	Per-result credits or subscription	Free
API key or account	None	Account	Required	None
Where data goes	Stays on your machine	Provider's servers	Provider's servers	Your machine
Rows per query	Dozens to hundreds	Close to zero	Dozens to thousands	A handful
Emails and socials	Built in	No	Often an add-on	Manual
Output	Clean CSV, 8 lead fields	Chat text	CSV or JSON	Spreadsheet

---

FAQ

Is this Google Maps scraper free? Yes. The kit is MIT licensed and the engine it runs is open source. There are no credits, subscriptions, or API keys. You only need Docker on your own machine.

Do I need a Google Maps API key or Google Places API? No. The kit drives a headless browser against Google Maps directly, so there is no API quota or billing.

Do I need Claude Code to use it? No. Claude Code makes it hands-free through a skill and slash commands, but scripts/scrape.py and scripts/scrape.sh run on their own from any terminal.

What data do I get for each business? Name, phone, email, website, category, address, rating, and review count by default. Add --socials for Instagram, Facebook, and LinkedIn, or --full for all ~34 raw fields.

How many leads can I scrape? Dozens to hundreds per query, depending on the area and depth. For large or repeated runs, add proxies (see Responsible use).

Does it work on Windows, Linux, and Apple Silicon Macs? Yes. Anywhere Docker runs. On Windows, use