Google Maps Scraper Kit

Local Google Maps lead extraction, operated by Claude.
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.

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.

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.

Project layout

google-maps-scraper-kit/
├── docker-compose.yml      local engine on 127.0.0.1:8080
├── .env.example            config template
├── scripts/
│   ├── scrape.py           Python CLI: single, batch, geocoding, socials, CSV
│   └── scrape.sh           bash CLI: single query
├── examples/               sample job body and batch keyword list
├── .claude/
│   ├── settings.json       pre-approved local commands for hands-free runs
│   ├── commands/           /scrape, /scrape-batch, /scrape-setup, /scrape-jobs
│   └── skills/google-maps-scraper/SKILL.md
├── CLAUDE.md               project instructions for Claude Code
└── SETUP.md                full setup guide

License

Built by Mahan. MIT licensed. Third-party components: CREDITS.md.