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

DEV Community: Jim Miller