DEV Community: Jim Miller

Google Maps Data via MCP: Cursor, Claude Code, Codex, and Claude Desktop

Jim Miller — Sat, 31 Oct 2026 01:21:12 +0000

Connect your AI client, pull one page of businesses, then check reviews or photos for a single place.

Disclosure: I work on growth at GMapsScraper.AI. This post is about the workflow: getting Google Maps business data into an AI client and keeping each request small enough to check by hand.

My usual question is which businesses operate in an area and which deserve a second look. I could write a script for that. With MCP, I ask in Cursor and the model calls the tool. The GMapsScraper.AI MCP server has three tools: business search, reviews, and photos.

I'll walk through it in Cursor. Setup for Claude Code, Codex, and Claude Desktop is further down; the prompts don't change between clients.

Connect Cursor

In your GMapsScraper.AI account, go to Dashboard > Settings > Create API Key. The snippets below use YOUR_API_KEY as the placeholder; paste your key there and keep the space after Bearer.

Add the server to .cursor/mcp.json for one project, or ~/.cursor/mcp.json for all of them:

{
  "mcpServers": {
    "gmapsscraper": {
      "url": "https://gmapsscraper.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

If the file already has servers, add the gmapsscraper entry inside the existing mcpServers object. If the project-level file sits in a shared repo, add it to .gitignore or use the home-directory version.

First search: one page, five rows on screen

For the example, I'm searching for roofing contractors with scrape_google_maps_search:

{
  "q": "roofing contractor",
  "page": 1,
  "ll": "@40.6970194,-74.3093048,11z",
  "hl": "en",
  "gl": "us",
  "extra": false
}

ll is @lat,lng,zoom; this one is centered in northern New Jersey at zoom 11. Always set it. Leave it out and the tool falls back to a default US location, and a table of roofers from the wrong region looks exactly as convincing as the right one. hl and gl default to en and us.

Here's the prompt:

Call scrape_google_maps_search once with the arguments above, page 1 only. Show up to five businesses with Name, Fulladdress, Phone, Website, Average Rating, and Review Count. Keep each Fid and Google Maps URL for later. Leave missing values blank. Don't call reviews, photos, or another page.

Five is a display limit, not a request size. The last sentence is what keeps the model from fetching more on its own.

The response has total, params, and data. The keys inside data aren't consistent: Fulladdress is one word, Review Count and Average Rating have spaces, and the contact fields are lowercase (emails, facebook_links). I copy them into prompts as-is.

Read the rows before asking for more

I check addresses first, then Categories, to see whether each business is the kind I searched for. If the page looks right, I filter what's already there instead of fetching more:

From the search data already returned, list businesses where Website is blank, with Name, Fulladdress, Phone, Review Count, and Google Maps URL. Label them "website not returned." No new tool calls.

The label is deliberate: a blank Website means the field came back empty, not that the business has no site.

I leave extra at false on this pass. Setting it to true asks for emails and social links, but the API doesn't return those fields on the free plan, and emails only appear when a listing has one.

Since emails came up: respect Google's terms and privacy and anti-spam laws (GDPR, CCPA, CAN-SPAM), collect only what you need, honor opt-outs, and don't target individual reviewers.

One place, one follow-up

Pick one business and pass its returned Fid to the next tool as fid, not an identifier the model rebuilds from the business name. Both follow-up tools also accept a Google Maps place URL as url, handy for a link a teammate pasted. Then choose reviews or photos, whichever answers your question.

Reviews

scrape_google_maps_reviews takes fid or url, page, and sort_by:

1: relevant
2: newest
3: highest rating
4: lowest rating

For the business I picked, call scrape_google_maps_reviews with its Fid as fid, page 1, sort_by 2. Summarize recurring service themes from that page without naming reviewers. Say that the summary covers page 1, newest first. Report next, then stop.

The response includes reviews, next, total, params, and place. If I'm looking for a recurring complaint, sort_by 4 gets there faster.

Photos

scrape_google_maps_photos takes fid or url plus page, with no sort_by. Its response has photos, next, total, url, params, and place.

Other clients

Claude Code

claude mcp add --transport http gmapsscraper https://gmapsscraper.ai/api/mcp --header "Authorization: Bearer YOUR_API_KEY"

Codex

Codex reads the key from an environment variable. Set GMAPS_API_KEY to your key where Codex runs (for example, export GMAPS_API_KEY=... in your shell profile), then pass the variable's name, not $GMAPS_API_KEY:

codex mcp add gmapsscraper --url https://gmapsscraper.ai/api/mcp --bearer-token-env-var GMAPS_API_KEY

Claude Desktop through mcp-remote

Claude Desktop's config file launches local stdio servers, so this goes through the open-source mcp-remote bridge, run via npx (Node required):

{
  "mcpServers": {
    "gmapsscraper": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://gmapsscraper.ai/api/mcp",
        "--header",
        "Authorization:${GMAPS_AUTH}"
      ],
      "env": {
        "GMAPS_AUTH": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Your key goes only in env.GMAPS_AUTH; leave Authorization:${GMAPS_AUTH} as written, with no space after the colon.

When the tools don't show up

Before rewording prompts, rule out the connection with MCP Inspector:

npx @modelcontextprotocol/inspector

Choose Streamable HTTP, enter https://gmapsscraper.ai/api/mcp, add an Authorization header with the value Bearer YOUR_API_KEY, connect, and run tools/list. You should see three tools:

scrape_google_maps_search
scrape_google_maps_reviews
scrape_google_maps_photos

If they appear here but not in your client, the problem is the client config: the env var for Codex, GMAPS_AUTH or npx for Claude Desktop, the JSON for Cursor. If they don't appear here either, check the key and header.

Quota

MCP uses the same key, rate limits, quota, and response shapes as the GMapsScraper.AI REST API, so the field names here carry over if you move to a script later. API usage is billed by request quota, separate from web app credits; check GMapsScraper.AI pricing before planning anything bigger than this walkthrough.

That's also why my first request is always a single page. If I got ll wrong, I've spent one request finding out.

Jim Miller, Growth at GMapsScraper.AI

A Google Maps Review Scraper for a Place Shortlist

Jim Miller — Fri, 30 Oct 2026 13:49:31 +0000

A Google Maps Review Scraper for a Place Shortlist

Fetch recent review pages with Python, keep each request tied to a place, and stop at a clear limit.

The shortlist already has names and addresses. The open question is whether recent reviews mention long waits.

For that, I use the GMapsScraper.AI reviews scraper. The Python script below fetches review pages for one place, saves the full responses, and tells me whether there's another page.

Which branch is this?

The request takes either fid or url. Use the Fid from a business search, or that business's Google Maps place URL. A business name alone won't work here. For chains, compare the full address with your shortlist before copying the reference.

Place Id looks like the obvious field to copy, but the reviews call wants Fid as fid or Google Maps URL as url. Place Id is a different key in the search response, so don't pass it as fid.

Without either reference, search first with POST /api/v1/search. It only needs q, but set ll, hl, and gl for location, language, and country; without ll, the search defaults to a US location. Compare the returned name and address with the shortlist row.

The GMapsScraper.AI API reference covers both calls. Once the address matches, copy that row's Fid or URL into the shortlist.

Review order

The place reference stays the same. Add page and sort_by:

Value	Order
`1`	Relevant
`2`	Newest
`3`	Highest rating
`4`	Lowest rating

I use 2 for this question. If you sort by highest or lowest rating instead, write that in your notes, so nobody reads a lowest-first page as typical.

Newest first isn't a date filter. There's no start or end date in this request. If you need a cutoff, such as the last few months, check the dates in the saved reviews before choosing which ones to include.

The response includes reviews, next, total, params, and place. The boolean next signals another page. The script's --max-pages cap limits each run, and I keep it at one until I've opened the JSON. Anything you conclude from that file covers only the reviews on that page.

Save the raw pages

Create an API key under Dashboard > Settings > Create API Key and set it in the shell you'll use:

export GMAPS_API_KEY='YOUR_API_KEY'

Save this complete block as fetch_reviews.py. It needs only Python's standard library.

import argparse
import json
import os
from pathlib import Path
from urllib.request import Request, urlopen

ENDPOINT = "https://gmapsscraper.ai/api/v1/reviews"


def positive_int(value):
    number = int(value)
    if number < 1:
        raise argparse.ArgumentTypeError("Use a positive integer")
    return number


def fetch(key, body):
    request = Request(
        ENDPOINT,
        data=json.dumps(body).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {key}",
            "Content-Type": "application/json",
        },
        method="POST",
    )
    with urlopen(request, timeout=60) as response:
        return json.load(response)


def main():
    parser = argparse.ArgumentParser()
    target = parser.add_mutually_exclusive_group(required=True)
    target.add_argument("--fid")
    target.add_argument("--url")
    parser.add_argument("--page", type=positive_int, default=1)
    parser.add_argument("--max-pages", type=positive_int, default=1)
    parser.add_argument("--sort-by", type=int, choices=(1, 2, 3, 4),
                        default=2)
    parser.add_argument("--out", required=True)
    args = parser.parse_args()
    key = os.environ.get("GMAPS_API_KEY", "").strip()
    if not key or key == "YOUR_API_KEY":
        parser.error("Set GMAPS_API_KEY to your real API key")
    reference = {"fid": args.fid} if args.fid else {"url": args.url}
    if not next(iter(reference.values())).strip():
        parser.error("The place reference cannot be blank")
    folder = Path(args.out)
    folder.mkdir(parents=True, exist_ok=False)

    for page in range(args.page, args.page + args.max_pages):
        payload = fetch(key, {
            **reference, "page": page, "sort_by": args.sort_by,
        })
        path = folder / f"page-{page}.json"
        path.write_text(
            json.dumps(payload, ensure_ascii=False, indent=2),
            encoding="utf-8",
        )
        if not isinstance(payload.get("next"), bool):
            raise ValueError(f"Inspect next in {path}")
        if "reviews" not in payload:
            raise ValueError(f"Missing reviews in {path}")
        print(f"Saved {path}; next={payload['next']}")
        if not payload["next"]:
            break


if __name__ == "__main__":
    main()

Here's a first call. Replace the placeholder with the place URL from the shortlist row:

python3 fetch_reviews.py \
  --url 'YOUR_GOOGLE_MAPS_PLACE_URL' \
  --sort-by 2 --max-pages 1 --out review-check-01

You can pass --fid 'YOUR_FID' instead of --url. The command refuses both together. If the saved page has next: true, you can continue with --page 2 and a new output folder. --max-pages counts pages from that starting point.

Read page one against the question

Open page-1.json and compare place with the shortlist address and params with the sort you asked for, before reading any review.

Inspect one saved review before choosing the text, date, and rating fields for your parser. The parser reads the saved file, so changing it costs no requests. Print the record keys locally:

import json
from pathlib import Path

saved = Path("review-check-01/page-1.json")
payload = json.loads(saved.read_text(encoding="utf-8"))
reviews = payload["reviews"]
print(type(reviews).__name__)
if isinstance(reviews, list) and reviews:
    first = reviews[0]
    print(list(first.keys()) if isinstance(first, dict) else first)

My notes for each place stay short: the question, the sort order, the pages I read, and the source page for each point. If I set a date cutoff, it goes in the note too. A teammate can then see what was read without fetching it again.

To call waiting time a common complaint, you need a count. Decide first whether comments like "slow service" belong under waiting time, then count mentions against the number of reviews you read.

When the run stops

Each response is written to disk before the loop looks at next. If a request fails, the script stops there with no retry, and pages saved before the failure stay in the folder. Open the last one before deciding which page to request next. Every run needs a new folder; putting the place in its name keeps pages from two branches apart.

If the last page says next: true, the cap stopped the run while more pages were available. If it says next: false, there are no further pages for that place and sort.

API calls draw on request quota, which is separate from web app credits, and each key is rate limited. Fetching the same place and page again spends another request, so I parse from the saved files.

Read with an MCP client if that's where you work

The GMapsScraper.AI MCP guide covers scrape_google_maps_reviews. It takes fid or url, page, and sort_by, with the same key, quota, rate limits, and response shapes as REST.

Give the client the fid or URL and a short instruction: fetch page one with sort_by: 2, report next, and stop. Then ask the client to list mentions of waiting time, quote each one, and state how many reviews it read. Check each quote against the full review before sharing the summary.

If page one doesn't settle the waiting-time question, fetch page two: --page 2 with a new folder, or ask the client for it.

Reviewer names, and sometimes the review text itself, can identify a person. Keep the saved JSON inside the team, quote only the lines the summary needs, and leave names out of anything that goes further. Check Google's terms and the privacy rules you work under before keeping those files past the task.

Jim Miller, Growth at GMapsScraper.AI

How to Scrape Google Maps Leads from Claude Desktop or Cursor with an MCP Server

Jim Miller — Thu, 22 Oct 2026 13:51:23 +0000

I wanted a quick list of roofers in one area without leaving Cursor. Names, phone numbers, websites, and review counts would do. I didn't need a long report. I needed a table I could check.

That's the workflow I'll walk through here: connect GMapsScraper.AI, fetch one search page, and use those rows to decide what to look at next. The GMapsScraper.AI MCP connection guide covers the remote server for business searches, reviews, and photos.

The useful part is being specific. “Find me leads” leaves the area and amount of work open. “Find roofers here, fetch page 1, then stop” gives you a clear first step.

Get your API key

Start by signing up for GMapsScraper.AI. Open Settings > Create API Key in the dashboard. You'll use the same key for MCP and the REST API.

The endpoint is https://gmapsscraper.ai/api/mcp. Choose Streamable HTTP as the transport. Authentication uses the header Authorization: Bearer YOUR_API_KEY.

Replace YOUR_API_KEY in the setup below with your key. Keep configs containing it out of shared repositories and screenshots. Pick the client you use; you don't need to set up all four.

Connect Cursor

Add this to .cursor/mcp.json for one project, or ~/.cursor/mcp.json for all your projects. If the file already has servers, keep them and add this entry:

{
  "mcpServers": {
    "gmapsscraper": {
      "url": "https://gmapsscraper.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

I'd make the first request small. One page gives you something you can read through before you spend more quota. Check the addresses and field names before asking Cursor to build a longer list.

Connect Claude Code

Run this command to add the HTTP server:

claude mcp add --transport http gmapsscraper https://gmapsscraper.ai/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Keep the space between Bearer and your key. It's a small detail that's easy to lose when copying a header.

Connect Claude Desktop with mcp-remote

Claude Desktop's config launches local stdio servers. Use the open-source mcp-remote bridge to reach this remote server. Add this entry to your Claude Desktop MCP config:

{
  "mcpServers": {
    "gmapsscraper": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://gmapsscraper.ai/api/mcp",
        "--header",
        "Authorization:${GMAPS_AUTH}"
      ],
      "env": {
        "GMAPS_AUTH": "Bearer YOUR_API_KEY"
      }
    }
  }
}

You'll need npx available locally. Leave Authorization:${GMAPS_AUTH} as written. Put your key in env.GMAPS_AUTH and keep its Bearer prefix. The bridge runs on your machine and connects to the remote MCP endpoint.

Connect Codex

Set the key in the shell you'll use to run Codex, then add the server:

export GMAPS_API_KEY='YOUR_API_KEY'
codex mcp add gmapsscraper \
  --url https://gmapsscraper.ai/api/mcp \
  --bearer-token-env-var GMAPS_API_KEY

The last argument takes the name of the environment variable. Keep GMAPS_API_KEY there. Don't replace it with the token or $GMAPS_API_KEY. That variable needs to stay available when you run Codex.

Check the connection

If you want to check the server directly, open MCP Inspector:

npx @modelcontextprotocol/inspector

Choose Streamable HTTP, enter the endpoint, and add an Authorization header with the value Bearer YOUR_API_KEY. Connect and run tools/list.

You should see scrape_google_maps_search, scrape_google_maps_reviews, and scrape_google_maps_photos. Next, try the search arguments below. I like this check because it lets me work through the connection setup before writing a longer prompt.

Start with a business search

scrape_google_maps_search accepts these parameters:

Parameter	What to put in it
`q`	Required search text.
`page`	Page number; defaults to `1`.
`ll`	Location as `@lat,lng,zoom`; defaults to a US location.
`hl`	Language; defaults to `"en"`.
`gl`	Country; defaults to `"us"`.
`extra`	Boolean requesting email and social fields.

Here's a first request:

{
  "q": "roofing contractor",
  "page": 1,
  "ll": "@40.6970194,-74.3093048,11z",
  "hl": "en",
  "gl": "us",
  "extra": false
}

Set the location yourself. Change ll, hl, and gl to match your search area, language, and country. Each call fetches one page, so put the page limit in your prompt too.

The response contains total, params, and a data array. For a first table, I'd use Name, Fulladdress, Phone, Website, Review Count, and Average Rating. Keep Google Maps URL and Fid handy for follow-up calls. Code that reads these fields needs their exact spelling and case.

Use extra: true to request emails and social links. The free API plan doesn't return those extra fields. Emails are only available when present, so leave missing contacts blank.

Before sorting the table, read a few rows. Are the addresses in the area you meant? Is the search term right for the businesses you want? Fix the search first if those basics look wrong.

Pull reviews or photos for one business

Once you've picked a business, reuse its returned Fid as fid, or pass its Google Maps place URL as url. That keeps the next request tied to the listing you chose.

scrape_google_maps_reviews takes fid or url, page, and sort_by. The sort values are 1 for relevant, 2 for newest, 3 for highest rating, and 4 for lowest rating. For recent reviews, use page: 1 and sort_by: 2.

The response includes reviews, next, total, params, and place. The boolean next tells you whether another page exists. When summarizing reviews, say which page you read so you can see the scope later.

scrape_google_maps_photos takes fid or url, plus page. It returns photos, next, total, url, params, and place. I'd inspect the returned photo data before deciding what belongs in an audit. A count alone won't tell you how old the photos are or how well the business is doing.

The GMapsScraper.AI REST API reference has the underlying request and response fields.

Five prompts I'd use

Start with a search, then work from the rows already in the conversation. Replace the location or supply the selected business when needed.

1. Get a small lead table

Find roofing contractors with ll "@40.6970194,-74.3093048,11z", hl "en", gl "us", and extra false. Fetch page 1 only. Show Name, Phone, Website, Average Rating, and Review Count. Leave blanks as blanks.

2. Make a review-count shortlist

From that page, show businesses with fewer than 30 reviews. Include their Google Maps URLs. No more tool calls.

3. Check missing websites

From that page, show Name, Fulladdress, and Phone where Website is blank. Label them “website not returned.” Don't guess domains. No new calls.

4. Read recent reviews

For the place URL I give you, fetch reviews page 1 with sort_by 2. Summarize repeated service themes without reviewer names. Show next, then stop.

5. Get photo data for an audit

Use the Fid of the business I pick. Fetch photos page 1 only. Show total and next, then summarize the returned photo data. Stop there.

A shortlist is where I start checking businesses. Fewer reviews doesn't tell me whether someone wants help. A blank website field means I should check the listing before pitching a website. Those checks make the list more useful than adding another page of names.

Keep an eye on quota

MCP uses the same rate limits, request quota, and response shapes as REST. Each API key is rate limited. API request billing is separate from web app credits.

The web app's free plan gives you 1,000 credits per month, with one credit per business. It allows up to two keywords per task and one concurrent task. Check the GMapsScraper.AI plans and pricing when choosing how to use it.

My approach is simple: read the search page, pick a business, then decide whether reviews or photos would help. Reusing the table for filters saves calls and makes it easier to follow your work.

If something goes wrong

If tools don't appear, try tools/list in Inspector with the same endpoint and key. Compare the settings with your client config. Check the JSON and header first. For Claude Desktop, check that npx is available too.

For an auth error, check the Bearer prefix. In Codex, check that the named environment variable contains the key. In Claude Desktop, check GMAPS_AUTH. If you hit a quota or rate limit, check API usage and pause further calls while you sort it out.

Keep collection focused

GMapsScraper.AI collects publicly available business data. Respect Google's terms and privacy and anti-spam laws, including GDPR, CCPA, and CAN-SPAM. Collect only what you need, honor opt-outs, and don't target individual reviewers.

Jim Miller, Growth at GMapsScraper.AI