gmaps-lead-atlas-mcp

An MCP server that lets an LLM find and qualify local business leads through the official Google Maps Places API.

Ask your assistant for "dental clinics in Austin with no website and fewer than 20 reviews" and get a contactable list back.

Install

claude mcp add gmaps-lead-atlas -e GOOGLE_MAPS_API_KEY=YOUR_KEY -- npx -y gmaps-lead-atlas-mcp

For Claude Desktop, Cursor, or Windsurf, add this to the MCP config file:

{
  "mcpServers": {
    "gmaps-lead-atlas": {
      "command": "npx",
      "args": ["-y", "gmaps-lead-atlas-mcp"],
      "env": { "GOOGLE_MAPS_API_KEY": "YOUR_KEY" }
    }
  }
}

Getting an API key

1. Create or select a project at https://console.cloud.google.com/
2. Enable Places API (New) at https://console.cloud.google.com/apis/library/places.googleapis.com
3. Create an API key at https://console.cloud.google.com/apis/credentials
4. Restrict the key to the Places API (New) under API restrictions
5. Enable billing on the project — Places API requires it even within the free tier

Set a budget alert first

This server calls a paid API. Before your first sweep, set a budget alert at https://console.cloud.google.com/billing/budgets so an unattended agent cannot surprise you.

Every tool response reports api_calls_used and session_calls_total so the model can see what it is spending. sweep_area is the only expensive tool — it defaults to 25 tiles and reports exactly how many it searched.

Tools

search_businesses

Search by query and area with lead-qualification filters.

| Parameter | Type | Notes | |---|---|---| | query | string | required, e.g. "plumbers" | | location | string | "Austin, TX" or "30.2672,-97.7431" | | radius_meters | number | only applies to coordinate locations | | included_type | string | Places type, e.g. "plumber" | | max_results | number | 1–60, default 20 | | filters.has_website | boolean | false selects businesses without a website | | filters.has_phone | boolean | false selects businesses without a phone | | filters.min_rating / max_rating | number | 0–5 | | filters.min_reviews / max_reviews | number | review count bounds | | filters.open_now | boolean | | | filters.price_levels | string[] | PRICE_LEVEL_INEXPENSIVE, etc. |

One caveat worth knowing: Google ranks results by prominence, which correlates with having a website and many reviews. Businesses without a web presence are ranked last and often fall outside the 60-result ceiling. A short list under has_website: false means the view is truncated, not that few such businesses exist. Use sweep_area for representative coverage.

get_business_details

Full details for up to 10 place IDs: opening hours, all phone formats, address components, reviews, business status. One API call per ID.

sweep_area

Tiles a city or region into overlapping circular searches and deduplicates, applying the 60-result ceiling per tile instead of per query. Parameters: query, area, included_type, tile_radius_meters (default 1500), max_tiles (default 25), filters.

Reports tiles_searched, tiles_total, and truncated so a partial sweep is never silently partial.

What this is not

This is a read-through query tool. It stores nothing, caches nothing, and writes no database. Results are returned to the model for the duration of a session. Using the Google Maps Platform to build a persistent derived dataset is prohibited by its Terms of Service — please keep it that way.

Places API does not return email addresses.

Development

npm install
npm test          # no API key needed
npm run typecheck
npm run build

Set GOOGLE_MAPS_API_KEY to additionally run the single live smoke test.

Releases publish from CI via npm trusted publishing — see RELEASING.md.

License

AGPL-3.0-or-later. See LICENSE.

You may use this commercially, including running a lead-generation business with it. If you offer it to others over a network, the AGPL requires you to release your source under the same license.