Developers / MCP server

Google Maps Scraper MCP Server

Connect your AI agent to synchronous business search and structured listing data through one secure MCP connection.

Get API key View Setup

Built for your agent

From a search to a useful dataset.

Give your agent the same business data workflow you use in your workspace.

Search businesses

Find businesses by keyword and location, with listing details your agent can organize and analyze.

Retrieve listing data

Read available addresses, contact details, ratings, and review counts in structured result pages.

Use results directly

Receive up to 20 businesses in structured JSON for research and applications.

How to connect

One endpoint, one auth header

Configure your client to use /api/mcp, then pass your API key in the authorization header.

POST https://gmapscrawl.com/api/mcp
Authorization: Bearer <YOUR_API_KEY>
Accept: application/json, text/event-stream

Streamable HTTP — your client handles protocol negotiation.

Bearer API key authentication — configure secrets outside prompts.

Connect your tools

Choose your MCP client

Keep your API key in a secure environment variable or your client’s protected input setting.

Add this server to .mcp.json. Make GMSCRAPER_API_KEY available in the environment that launches Claude Code.

{
  "mcpServers": {
    "google-maps-data": {
      "type": "http",
      "url": "https://gmapscrawl.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${GMSCRAPER_API_KEY}"
      }
    }
  }
}

Claude Code documentation ↗

Need step-by-step guidance? Read the MCP setup guide

Your first result

Connect, test, then run a live search

Start with a test credential and simulated data. Switch to live only when you are ready to use your API allowance.

1. Prepare your API workspace
Sign in, select the API product, and check your API entitlement. Online and Extension plans have separate allowances. Create a test key with scrapes:write; your plan must permit MCP even for a test connection.
2. Connect your client
Copy the client configuration, supply the key through its secret setting, and reconnect. Confirm that search_google_maps appears in the tool list. No OAuth connection is needed.
3. Verify one result
Ask your agent to call the tool once with the example below, replacing the request ID. A test response has structuredContent.simulated: true. Inspect total and businesses; test records are not real leads.

Arguments for search_google_maps

{
  "q": "coffee shops in Seattle",
  "page": 1,
  "hl": "en",
  "extra": false,
  "client_request_id": "replace-with-a-fresh-uuid"
}

Generate a fresh UUID for each new search. Keep that ID and the input unchanged when retrying a timeout. The example does not execute a search from this page.

For live use, configure a live key and run one search with extra: false first. Each successful source-page search uses one API request unit, including empty results, and returns at most 20 businesses. Check service status if live searches are unavailable.

Read the returned businesses directly from structuredContent; this tool does not require job polling. Fields can be missing, and source observations may be cached. Ask your agent to save the returned JSON or a reviewed table in your own application. MCP does not expose an export or email-sending tool.

Learn how to interpret business fields, protect API credentials, and handle failures and retries.

Connection help

Troubleshoot the next step

Check the connection and tool response to identify the next action.

No tools appear: Confirm the remote HTTP endpoint is /api/mcp, reload the client's MCP connection, and check that its process can read your key. The expected tool is search_google_maps.
401 / unauthorized: Check the key, active API entitlement, expiry, and allowed IPs. A browser login does not authenticate MCP. Never paste a key into a prompt.
403 / forbidden: Check that the API plan includes MCP, the key permits scrapes:write, and its custodian is an active workspace member.
invalid_request: Use the published input fields and a client_request_id of 16–128 characters. Replace it for new work; preserve it with identical input for retries.
rate_limited or quota_exceeded: Honor retry_after for rate limits. Stop at a quota denial and check API usage; additional keys do not add allowance.
capability_unavailable: Check service status. Live searches require enabled cloud scraping; changing clients cannot bypass a service restriction.
Timeout or isError: true: Read the tool's error block even if HTTP returned 200. Retry only retryable failures with identical input and the same request ID, within your task deadline.

Built for your workflow

Built for data-aware AI workflows

Move from a question to structured local business research without switching tools.

Prospecting research

Build a focused list of local businesses for sales research and outreach planning.

Local market analysis

Compare categories, ratings, and review counts across the businesses in your dataset.

Listing enrichment

Bring available business and contact fields into CRM, reporting, or internal workflows.

Put it to work

Example prompts to try

Try a focused request in your connected client. With a test key, ask your agent to label the results as simulated.

Prompt
“Find one page of coffee shops in Seattle and return their website, phone number, rating, and review count.”

Prompt
“Search for restaurants in Portland and compare the returned business categories and ratings. Point out missing data.”

Prompt
“Search one page of plumbers in Austin and format the returned businesses as a table with names, phone numbers, and websites.”

Frequently asked questions

What is the Google Maps Scraper MCP server?

It is a remote Model Context Protocol server that lets compatible AI agents search for up to 20 businesses and receive results directly using your API-workspace credentials.

Which MCP transport does it use?

The server uses stateless Streamable HTTP at https://gmapscrawl.com/api/mcp. /mcp remains a compatibility alias. Your client initializes the connection and negotiates the protocol version.

How do I authenticate the MCP server?

Configure Authorization: Bearer with your API key in the client’s secret configuration. Browser login cookies do not authenticate this endpoint, and keys should never go in a prompt or URL.

Can I connect Claude Code, Cursor, VS Code, or Codex?

Yes, with a version that supports remote HTTP MCP and custom authorization headers. Use the client configurations above and ensure the configured environment variable is available to that client.

What Google Maps data can my agent retrieve?

Business searches return available listing attributes, contact details, ratings, and review counts. The server exposes only search_google_maps.

Do I need an API plan?

Yes. MCP is available on free and paid API plans. Use an API key from your API workspace for test or live searches. MCP shares your API allowance; an Online subscription does not include it. Test credentials validate the integration with simulated fixtures without consuming search units.

Take the next step

Give your AI agent Google Maps data.

Create an API key, connect the MCP server, and bring business research into your preferred client.

Get API key