# 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

```bash
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:

```json
{
  "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

```bash
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](RELEASING.md).

## License

AGPL-3.0-or-later. See [LICENSE](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.