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.

Related MCP server: Local Business Data MCP Server

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

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.

Deploy as a remote MCP server

All of the configs above spawn the server locally over stdio, which means it only works on the machine the code is checked out on. To use it from anywhere, run it on a server over the Streamable HTTP transport instead and point your clients at a URL.

dist/mcp/http.js is that server. It's stateless — a fresh MCP server per request, no session state shared between clients — and requires a bearer token.

1. Point DNS at the host

Add an A record for the subdomain you want, pointing at your VPS's public IPv4:

That gives maps.prompthero.in. Do this before issuing a certificate — Let's Encrypt validates over HTTP, so the name has to resolve and ports 80/443 have to be reachable, or issuance fails.

Confirm it has propagated: dig +short maps.prompthero.in

On Cloudflare, set this record to DNS only (grey cloud), not Proxied. Cloudflare's proxy drops any origin response that takes longer than 100 seconds (error 524) on Free/Pro plans. A scrape routinely runs longer than that, so a proxied record would kill most real requests. The bearer token — not Cloudflare — is what protects this endpoint.

2. Run it with Docker

On the host:

git clone https://github.com/rahul-bhatt43/maps-scrapper.git && cd maps-scrapper
cp .env.example .env

# Set the token — this is the only credential protecting the endpoint.
sed -i "s|^MCP_AUTH_TOKEN=.*|MCP_AUTH_TOKEN=$(openssl rand -hex 32)|" .env

# Then set DOMAIN and ACME_EMAIL in .env, and bring it up with HTTPS:
docker compose --profile tls up -d --build

Caddy provisions a Let's Encrypt certificate automatically, so the server lands at https://maps.prompthero.in/mcp.

If something already serves prompthero.in on this host, don't use --profile tls. Caddy binds ports 80 and 443 and will collide with your existing nginx/Caddy/Traefik. Use the existing-proxy path below instead.

Already running a reverse proxy?

Bring it up without the profile:

docker compose up -d --build

The app then publishes on 127.0.0.1:8787 only — deliberately, so nothing is exposed until something terminates TLS in front of it. Add a vhost to your existing proxy pointing there. The timeouts matter: a large scrape holds one response open for minutes, and default proxy timeouts (nginx's is 60s) will cut it off mid-run.

nginx:

server {
    server_name maps.prompthero.in;
    listen 443 ssl;
    # ... your existing ssl_certificate lines, or run certbot for this name

    location / {
        proxy_pass http://127.0.0.1:8787;
        proxy_http_version 1.1;
        proxy_set_header Host $host;

        # A 100-place scrape can run for many minutes on one request.
        proxy_read_timeout 30m;
        proxy_send_timeout 30m;

        # Responses stream as SSE — buffering would hold them back.
        proxy_buffering off;
    }
}

Caddy (adding to an existing Caddyfile):

maps.prompthero.in {
	reverse_proxy 127.0.0.1:8787 {
		transport http {
			response_header_timeout 30m
			read_timeout 30m
		}
	}
}

3. Check it

curl https://maps.prompthero.in/healthz
# {"ok":true,"scrapes":{"size":3,"available":3,"waiting":0}}

# Should be 401 — proves auth is actually on:
curl -o /dev/null -w '%{http_code}\n' -X POST https://maps.prompthero.in/mcp

Logs, if something's off: docker compose logs -f maps-scrapper

Alternative: run it without Docker

Works fine, with one trade-off: playwright install-deps installs ~40 shared libraries system-wide via apt. On a host already serving other sites that's more invasive than a container, and harder to cleanly remove later. It does use roughly 300–400MB less disk.

# Node 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# A dedicated unprivileged service user — Chromium should not run as root.
# No --create-home: /etc/skel would leave dotfiles in the directory and git
# refuses to clone into a non-empty one. Clone first, then take ownership.
sudo useradd --system --home-dir /opt/maps-scrapper --shell /usr/sbin/nologin mapsscraper
sudo git clone https://github.com/rahul-bhatt43/maps-scrapper.git /opt/maps-scrapper
sudo chown -R mapsscraper:mapsscraper /opt/maps-scrapper
cd /opt/maps-scrapper

# -H sets HOME to the service user's directory, so npm's cache lands somewhere
# it can actually write. devDependencies are needed for tsc, so no --omit=dev.
sudo -u mapsscraper -H npm ci --ignore-scripts
sudo -u mapsscraper -H npm run build

# Chromium: the system libraries need root, the browser itself does not.
sudo npx playwright install-deps chromium
sudo -u mapsscraper -H env PLAYWRIGHT_BROWSERS_PATH=/opt/maps-scrapper/.playwright \
  npx playwright install chromium

# The token lives in this file, so keep it readable only by the service user.
sudo -u mapsscraper -H cp .env.example .env
sudo -u mapsscraper -H sed -i "s|^MCP_AUTH_TOKEN=.*|MCP_AUTH_TOKEN=$(openssl rand -hex 32)|" .env
sudo chmod 600 .env
sudo -u mapsscraper -H mkdir -p profiles output

Then /etc/systemd/system/maps-scrapper.service:

[Unit]
Description=maps-scrapper MCP server
After=network.target

[Service]
Type=simple
User=mapsscraper
WorkingDirectory=/opt/maps-scrapper
EnvironmentFile=/opt/maps-scrapper/.env
Environment=NODE_ENV=production
Environment=PLAYWRIGHT_BROWSERS_PATH=/opt/maps-scrapper/.playwright
Environment=MCP_HTTP_HOST=127.0.0.1
Environment=PROFILE_ROOT=/opt/maps-scrapper/profiles
Environment=OUTPUT_DIR=/opt/maps-scrapper/output
ExecStart=/usr/bin/node dist/mcp/http.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Two things to check before enabling it:

• ExecStart must be the real node path. Confirm with command -v node. If it points somewhere under a home directory (/home/john/.nvm/...), the service user can't reach it — install Node system-wide instead.

• No NoNewPrivileges=true here, deliberately. It blocks setuid binaries, which breaks Chromium's chrome-sandbox helper. Ubuntu 24.04 also restricts unprivileged user namespaces by default (kernel.apparmor_restrict_unprivileged_userns=1), so Chromium falls back to exactly that helper. Setting both would leave it with no working sandbox at all.

sudo systemctl daemon-reload
sudo systemctl enable --now maps-scrapper
sudo systemctl status maps-scrapper
curl 127.0.0.1:8787/healthz

Logs: journalctl -u maps-scrapper -f. Reverse proxy setup is identical to the Docker path above — it's the same port.

To update later: git pull && npm ci --ignore-scripts && npm run build && sudo systemctl restart maps-scrapper.

Environment variables

Point clients at it

Run this on any machine you want the tool available on — nothing needs to be checked out there.

Claude Code:

claude mcp add --transport http maps-scrapper https://maps.prompthero.in/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Claude Desktop, Antigravity, and other clients that take a JSON config:

{
  "mcpServers": {
    "maps-scrapper": {
      "type": "http",
      "url": "https://maps.prompthero.in/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

The tool and its inputs are identical to the stdio version, with one difference: saveToFile is reduced to a bare filename written into OUTPUT_DIR. Directory components are stripped, so a remote caller can't write outside that directory.

Things worth knowing before you rely on it

• Datacenter IPs get blocked faster. Google walls automated traffic from cloud ranges considerably sooner than from a residential connection. Keep max modest and don't loop; if you start seeing the blocked-session error routinely, a residential proxy is the fix.

• Concurrency is capped by design. launchPersistentContext takes an exclusive lock on its profile directory, so each concurrent scrape gets its own leased directory from a pool sized by MAX_CONCURRENT_SCRAPES. Requests beyond that wait for a free slot rather than failing. Raising it costs RAM and raises your block risk — it does not make Google faster.

• Scrapes are slow and synchronous. A 100-result run can take many minutes on one HTTP request. Node's request timeout is disabled for this reason, but a proxy or client with its own timeout will still cut it off.

• shm_size matters. Chromium crashes on Docker's 64MB /dev/shm default; compose sets it to 2GB. If you deploy without compose, set it yourself or you'll get "Target closed" mid-scrape.

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
    profilePool.ts               # leases one browser profile dir per concurrent scrape
  output/writer.ts        # JSON/CSV output
  mcp/
    tool.ts                # shared MCP tool registration (used by both transports)
    server.ts               # stdio transport — for locally-spawned clients
    http.ts                  # Streamable HTTP transport — for remote deployment
  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.