MapsData

npx add-mcp 'https://mapsdata.ai/mcp'

Connect an AI agent

MapsData is a remote MCP server, so an AI assistant can build your lead lists directly. Connect it once and you can ask Claude or another agent to find plumbers in Texas, and it will check the category, start the scrape, and hand you the file when it is done.

MCP is the Model Context Protocol, an open standard for giving an assistant access to a tool. Our server is at:

https://mapsdata.ai/mcp

Included on every paid plan, same as the REST API, and it uses the same API keys. Scrapes started by an agent count against the same monthly allowance as everything else.

Connecting

Authentication is a bearer token: your MapsData API key, created in Settings. See authentication for how keys work.

Claude Code

claude mcp add --transport http mapsdata https://mapsdata.ai/mcp \ --header "Authorization: Bearer mdk_live_..."

Cursor

In ~/.cursor/mcp.json, or the project's .cursor/mcp.json:

{ "mcpServers": { "mapsdata": { "url": "https://mapsdata.ai/mcp", "headers": { "Authorization": "Bearer mdk_live_..." } } } }

Anything else

Any client that speaks streamable HTTP MCP and lets you set a header will work. The server is stateless: it issues no session id, and every call is a single POST.

Hosted connectors

Directories like Claude.ai's have nowhere to put a header, so they use OAuth instead. MapsData supports that: dynamic client registration, an authorization code flow with PKCE, and rotating refresh tokens. Point the connector at https://mapsdata.ai/mcp and it discovers the rest, then sends you to a consent screen that names the application and states plainly that approving it lets that application spend your monthly lead allowance.

Approved connections appear in Settings beside your API keys, and disconnecting one takes effect immediately.

Tools

Tool	What it does
mapsdata_search_categories	Find the exact Google Maps category to scrape
mapsdata_list_regions	Valid region names for a country
mapsdata_get_usage	Allowance left this cycle, and the largest scrape you can start right now
mapsdata_start_scrape	Start a scrape. Supports a dry run.
mapsdata_get_scrape	Check one scrape
mapsdata_list_scrapes	Recent scrapes, newest first
mapsdata_get_download_link	A 15-minute link to the results
mapsdata_cancel_scrape	Cancel a queued or running scrape

Cancel is marked destructive, so a well-behaved client will ask you before running it. That is deliberate: cancelling a running scrape still bills the leads already delivered.

A worked example

Ask for what you want in plain language:

Find me 500 plumbers in Texas with email addresses.

A well-behaved agent will confirm the category is scrapable, start the job, and then stop rather than sitting in a loop:

> mapsdata_search_categories(query: "plumb") ["Plumber", "Plumbing supply store"] > mapsdata_start_scrape(query: "Plumber", states: ["Texas"], total_limit: 500) {"job_id": "8f2c...", "status": "queued", "poll_after_seconds": 60, "next_action": "Tell the user the scrape is queued ... then STOP."} "Started a scrape for 500 plumbers in Texas. It usually takes anywhere from a few minutes to a couple of hours. MapsData will email you when it's done, or ask me to check on it."

Later, ask it to check and fetch the file:

> mapsdata_get_scrape(job_id: "8f2c...") {"status": "completed", "leads_scraped": 480, "leads_with_email": 151, "next_action": "Call mapsdata_get_download_link."} > mapsdata_get_download_link(job_id: "8f2c...") {"download_url": "https://...", "filename": "Plumber.csv", "expires_in_seconds": 900}

Why it will not sit and poll

A scrape runs for minutes to hours, which is an awkward shape for an assistant. Every job response carries a poll_after_seconds figure and an explicit next_action instruction telling the agent to report and stop. Agents follow a field in the response far more reliably than they follow a description, so both are there.

If an agent does loop anyway, the rate limits stop it: 120 calls a minute per key, 300 a minute across your whole workspace, and 10 scrape submissions a minute. An edge limit sits in front of all of that.

An agent also cannot overspend your allowance in a single call. total_limit is capped at the leads you have left this cycle, and mapsdata_get_usage reports max_rows_this_scrape so a well-behaved agent sizes the request before making it. When a scrape is reduced, the response says so and tells the agent to pass that on.

When something is wrong

Tool failures come back as readable errors the agent can act on rather than as protocol faults, and they name the tool that fixes the problem. Asking for a category that does not exist tells the agent to call mapsdata_search_categories; using TX instead of Texas tells it to call mapsdata_list_regions. In practice the agent corrects itself and retries without involving you.

Safety

• Your key is your workspace's quota. An agent holding it can spend the month's allowance. Use a key made for this, so you can revoke it without breaking anything else.
• Read-only if you prefer. Choose "Read only" when you create the key in Settings and the assistant can check and download existing scrapes but never start or cancel one.
• Cancelling costs money. It is flagged destructive so your client asks first. Keep that confirmation on.