Guide · Agent skill
How to use the Google Maps Scraper agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The google-maps-scraper skill lets an AI agent turn a plain request, such as finding dentists in Berlin, into Google Maps searches and run the open-source gosom scraper on your own computer using Docker. This guide is for people who have never installed an agent skill and want local business lists from Google Maps. By the end you will know how to install the skill, make a request, check progress and work with the results.
Google Maps Scrapergosom/google-maps-scraper · MIT Download the skill Quick start
- 1Get the skill ZIP. Download the google-maps-scraper ZIP from this directory page.
- 2Install Docker and Node.js. Make sure both are installed and working. On Windows, use WSL.
- 3Place the skill folder. Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. Or upload it under Settings → Capabilities → Skills in the Claude apps.
- 4Ask in plain language. Request something like finding dentists in Berlin and confirm the location and coverage if asked.
- 5Choose a proxy path. Use an existing proxy, view sponsor recommendations or continue without one. Enter any credentials only in your terminal.
- 6Let the validation run finish. The agent runs one small test query first and only starts the full crawl if it produces results.
- 7Review and save results. Check the preview of up to 20 rows, then ask the agent to save, filter or analyze the full set.
What an agent skill is and what this one does
An agent skill is a folder of instructions and helper scripts that an AI agent can load when a request matches its description. This skill's description covers finding businesses, leads, emails, reviews, ratings and contact details from Google Maps.
Once the skill is installed, the agent can prepare the search queries from your request, run the scraper locally with Docker, monitor the run and show you a preview of the businesses it found, with details such as phone, website, address and rating. You can also save the results as a file. Extracting emails or reviews happens only when you ask for it.
Requirements before you install
The skill needs Docker and Node.js. The compatibility note says it works on macOS, Linux, or Windows through WSL. The scraper will not run without Docker and Node.js, and the agent uses npx for the optional skill update check.
A proxy is optional. You only need a proxy provider account and a proxy URL if you choose to use one.
- Docker
- Node.js
- npx (for the optional skill update check)
- Optional: a proxy provider account and proxy URL
Install the google-maps-scraper skill
Download the ZIP of the skill from this directory page and unzip it. Then place the folder in one of these locations, depending on how you want to use it.
For a personal install across projects, put it in ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder. If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload
Run your first Google Maps search with a natural request
You do not need special syntax. Ask in plain language, for example: find dentists in Berlin, scrape Google Maps for local business leads, or collect Google Maps reviews for a named business type and place.
The agent infers sensible defaults and asks only for missing essentials: the business type or search phrase, the location, and the coverage you want (a quick sample, a normal search, or comprehensive area coverage). By default it uses English, CSV output, no email extraction, no extra reviews and shallow depth. It summarizes the configuration before setup.
Before the full crawl, the agent runs a small validation crawl with one representative query. The validation succeeds only when the container exits successfully and produces at least one result. The validation run uses a separate output directory under /tmp. The command the agent uses looks like this:
bash "$SKILL_DIR/scripts/run-local.sh" --queries /tmp/gmaps-validation-queries.txt --output-dir /tmp/gmaps-validation-output --depth 1Choose a proxy path and keep credentials safe
The agent explains whether your volume makes a proxy optional or recommended and asks you to pick one path: use an existing proxy, see proxy sponsor recommendations, or continue without a proxy. Continuing without one is a valid choice.
If you have a proxy URL, the skill runs a masked local prompt. You type the credentials directly into your terminal. The skill is designed never to ask for proxy credentials in chat, and it never prints or logs them. The scraper receives the proxy through a proxies file, not inline on the command line.
If you request recommendations, the skill shows three providers. These providers sponsor the project and the links are referral links. You can reject all three, use another provider or skip the proxy.
- Never paste proxy credentials into the chat
- Proxies are not required for every crawl and do not guarantee results
Monitor the crawl and read the results
The full crawl uses the same helper with your complete query file. The agent reports that the crawl has started, whether the first image download may add startup time, the container state, elapsed time and current result count. It checks progress periodically and does not promise an exact completion time.
When the crawl succeeds, the agent counts the full result set and shows at most 20 preview rows with the most useful fields, such as business name, category, rating and review count, phone, website, address and emails when requested. Partial output is kept if a crawl fails or is interrupted. You can then ask it to save, analyze, filter, convert or expand the crawl.
- Business name, category, rating and review count
- Phone, website and address
- Emails, only when you requested them
node "$SKILL_DIR/scripts/status-local.mjs"Safety, scripts and network use
This skill runs scripts and uses the network. Its allowed tools include Bash for node, bash and docker commands, plus Read and Write. The scripts run Docker containers that use the open-source image gosom/google-maps-scraper.
Before you collect data, check Google Maps terms and local privacy rules. The skill itself notes that collecting contact details can carry legal and reputational risk, so review your use case before running large or sensitive crawls.
- Runs scripts: yes
- Uses network: yes
- Scripts are bundled in the skill's scripts folder and are readable before you run them
What people use it for
- Building a local business lead list for a sales team, such as dentists or restaurants in one city.
- Getting Google Maps business data into a CSV file for analysis.
- Collecting ratings and review counts for a set of local businesses.
- Running a guided first-time setup of a local scraper without writing code.
Frequently asked questions
How do I install the google-maps-scraper skill?
Download the skill ZIP from this directory page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings → Capabilities → Skills. Docker and Node.js must also be installed.
What do I need to run the Google Maps scraper skill?
You need Docker and Node.js on macOS, Linux, or Windows through WSL. npx is used for the optional skill update check. A proxy provider account is optional and only needed if you choose to use a proxy.
Is the Google Maps scraper skill free?
The skill is released under the MIT licence, and the scraper it runs is open source. The source does not state prices for any proxy provider, so check those providers directly if you use one.
Do I need a proxy to use it?
No. The skill says a proxy is optional for a small validation or shallow crawl. Proxies can be considered for many queries, higher concurrency or repeated crawls, but they do not guarantee results.
Why does the scraper fail or return few results?
The skill's recovery guidance covers failed setup and crawls, and it preserves partial output. Google may block a local connection, and results depend on the query, location and Google's behaviour. Ask the agent to check the status and follow its recovery steps.
How does this compare to other Google Maps scrapers?
This skill is specifically a guided, local, Docker-based workflow that an agent runs for you. Hosted scraping services or manual copy-paste from Google Maps work differently, and the source does not compare them, so weigh them on your own needs.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a sales, marketing or analyst team that wants a guided, local way to build Google Maps business lists in CSV, and you can install Docker and Node.js. Pick something else if you cannot install those tools, or if you need guaranteed complete results or large, sensitive contact-data collection without first checking Google Maps terms and local privacy rules.
Download the skill