maps-scrapper

A self-hosted Google Maps places scraper — a free alternative to Apify's crawler-google-places actor. Scrapes Google Maps directly with a headless browser (Playwright), no API key required. Available both as a CLI and as an MCP server so AI assistants (Claude Desktop, Claude Code, etc.) can call it as a tool.

Note on Terms of Service: this scrapes Google Maps' web UI directly rather than using Google's paid Places API, which is against Google's Terms of Service. It's intended for personal, low-volume use. Google may rate-limit or block sessions that scrape aggressively — keep max reasonable and don't run it in a tight loop.

What it extracts

For each place: name, category, rating, review count, price level, address, phone, website, opening hours, coordinates (lat/lng), and its Google Maps URL.

Not every place has every field (e.g. missing phone/website is normal) — those come back as undefined/absent rather than causing an error.

Install

npm install     # also downloads a Chromium binary for Playwright
npm run build

CLI usage

node dist/index.js run -q "coffee shops" -l "Austin, TX" -m 50

or, once you npm link (or install globally), use the maps-scrape bin directly:

maps-scrape run -q "coffee shops" -l "Austin, TX" -m 50

Flags

Flag	Description	Default
-q, --query	Search query, e.g. "coffee shops"	required
-l, --location	Location, e.g. "Austin, TX"	required
-m, --max	Max results to collect	100
-o, --out	Output file path	./output/<query>-<location>-<timestamp>.<ext>
-f, --format	json or csv	json
--headless	true or false — set false to watch the browser work	true
--min-delay / --max-delay	Randomized delay range (ms) between actions	800 / 2000
--profile-dir	Persistent browser profile directory (keeps consent dialogs from reappearing)	.maps-scraper-profile

Results are written to disk after every place is scraped, so interrupting with Ctrl+C still leaves a valid, complete file with whatever was collected so far.

MCP usage

The MCP server exposes one tool, search_google_maps_places, with inputs query, location, optional max (1–100, default 20), and optional saveToFile (a path to also persist the results as JSON/CSV). It returns the scraped places as JSON.

Run it standalone to confirm it starts:

npm run mcp
# or: node dist/mcp/server.js

It communicates over stdio, so it's meant to be launched by an MCP client, not used interactively.

Add to Claude Code

claude mcp add maps-scrapper -- node D:\random\maps-scrapper\dist\mcp\server.js

(Adjust the path if your project lives elsewhere. Run this from anywhere — it's not tied to being inside the maps-scrapper directory.)

Add to Claude Desktop

Edit your claude_desktop_config.json (Claude menu → Settings → Developer → Edit Config) and add:

{
  "mcpServers": {
    "maps-scrapper": {
      "command": "node",
      "args": ["D:\\random\\maps-scrapper\\dist\\mcp\\server.js"]
    }
  }
}

Restart Claude Desktop after saving. Then you can ask things like "find highly-rated taco places in San Antonio, TX and list their phone numbers" and it'll call the tool directly.

Add to Antigravity

Antigravity's MCP config lives at ~/.gemini/config/mcp_config.json (Windows: C:\Users\<you>\.gemini\antigravity\mcp_config.json). Easiest way to find/edit it: in the IDE, open the agent panel's ... menu → Manage MCP Servers → View raw config (or Settings → Customizations → Open MCP Config).

Add an entry using the standard mcpServers format:

{
  "mcpServers": {
    "maps-scrapper": {
      "command": "node",
      "args": ["D:\\random\\maps-scrapper\\dist\\mcp\\server.js"]
    }
  }
}

Save, then hit refresh in the Installed MCP Servers panel.

Add to OpenCode

OpenCode uses a different shape — mcp key, type: "local", and command as a single array (binary + args together). Edit opencode.json in your project, or ~/.config/opencode/opencode.json for a global setup:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "maps-scrapper": {
      "type": "local",
      "command": ["node", "D:\\random\\maps-scrapper\\dist\\mcp\\server.js"],
      "enabled": true
    }
  }
}

Both Antigravity and OpenCode spawn the server on demand — nothing needs to be running ahead of time, just make sure npm run build has been run at least once so dist/mcp/server.js exists.

Project structure

src/
  index.ts              # CLI entry point
  cli/args.ts            # commander option parsing
  scraper/
    scrape.ts             # shared core scraping logic (used by both CLI and MCP)
    selectors.ts           # all Google Maps DOM selectors/regex, centralized
    browser.ts              # Playwright browser/context launch
    search.ts                 # search navigation, consent dialogs, result-shape detection
    listPanel.ts               # scroll-to-load-more results list
    detailPanel.ts              # per-place field extraction
  output/writer.ts        # JSON/CSV output
  mcp/server.ts            # MCP server (stdio transport)
  main.ts                    # CLI orchestration (writes files, handles Ctrl+C)

Known limitations

• DOM fragility: Google's Maps class names are build-hashed and rotate on redesigns. Selectors deliberately prefer role/aria-label/data-item-id over class names, and all live in src/scraper/selectors.ts — a breakage should only need edits there.
• CAPTCHA / rate limiting: repeated automated access can trigger an "unusual traffic" wall. The tool detects and reports this rather than trying to bypass it.
• Hours field: the most fragile extraction — always treated as optional/best-effort.
• Review counts: occasionally unavailable — Google sometimes serves a reduced "limited view" of a place (even to real signed-out users) that omits them entirely.