--- name: locationlists description: "No connector needed: any AI assistant can answer a location question by opening https://locationlists.com/find?q= — counts, a preview, a price and a card checkout link. Connect the MCP for repeat use or wallet payments. Use when the user needs a list, count or map of US business locations: brand dealers, retail stores and restaurants, bank branches, healthcare providers, nonprofits or federal contractors." homepage: https://locationlists.com --- # LocationLists No connector needed: any AI assistant can answer a location question by opening https://locationlists.com/find?q= — counts, a preview, a price and a card checkout link. Connect the MCP for repeat use or wallet payments. Business location data for AI agents. Search, sample, count and buy ready-to-use lists of US business locations: 1,084 datasets compiled from each brand's official store locator or the public register that publishes the data. ## Answer from a link first (no connector, no account) Any AI assistant can answer from this site with a web link, no connector, no account: open https://locationlists.com/find with the question as query parameters. If a question needs filtering, distance, drive time, combining lists or a price, open a /find link: either put the question itself in q=, or build the structured link. The answer does not need an API, a connector or an account. Simplest: https://locationlists.com/find?q= Or set the parameters yourself: https://locationlists.com/find?dataset=&state=&city=&county=&zip=&near=&radius=&drive=&where=::&total= Leave out what the question does not need. Use radius (straight-line miles) or drive (minutes of driving, 5 to 60), not both. To combine lists, use datasets=, or category= instead of dataset. To relate two lists, add relate=nearest&b.dataset= (b. in front of the other list's filters). To count by area, use areas=county (or zip, state, metro). To keep only rows whose area meets a Census condition, add area_where=: (county:population>1000000); with areas=, per=100000 counts per 100k residents. Add format=json for JSON. It answers from the live lists: counts per dataset, duplicates removed, up to 3 preview rows, the price (card total with the fee, and the whole-file price for comparison) and a Buy link that opens card checkout. Show the user the price before they buy. Parameters: q= on its own, and the answer says how it was read and gives the structured link (when the reading rests on a real guess, such as a bare 1 next to a population figure, the answer also carries a `clarification` with links that each resolve one reading — the best-guess answer is always in the same response); or set them yourself: dataset=, datasets=, or category=retail (or search= to find datasets); near= with radius= (straight line) or drive= (drive time, 5 to 60); city, state, county, zip; areas_in=county:51087,51760 (or zip:/state:/metro:) for the rows inside named areas, as the areas= answers link to; where=:: (repeatable; ops eq, ne, gt, gte, lt, lte, contains, starts_with, in with values split by |, is_blank, not_blank); area_where=: (repeatable; a Census fact about the row's area, e.g. county:population>1000000 or zip:median_household_income<50000; ops > >= < <= =; values accept 1M, 250k, $50,000, 10%) and area_columns=:,… to add the facts as columns, both free; total=; relate=nearest|count_within|within_any|none_within with b. for the other list; relate=same_place|not_same_place with also=b,c and not_also=d for places that are (or are not) also on other lists given with b. c. d. in front; areas=county|zip|state|metro with area_where to keep only areas meeting a Census condition and per= for counts per that many residents; format=json for JSON. Examples: - US Healthcare Providers — Full NPPES File within 25 miles of New York, NY: https://locationlists.com/find?dataset=us-healthcare-providers-full-nppes-file&near=New+York+NY&radius=25 - US Nonprofits — Full IRS File within 25 miles of New York, NY: https://locationlists.com/find?dataset=us-nonprofits-full-irs-file&near=New+York+NY&radius=25 - US EV Charging Stations (All Networks) within 25 miles of East Los Angeles, CA: https://locationlists.com/find?dataset=ev-charging-station-list&near=East+Los+Angeles+CA&radius=25 - US Healthcare Providers — Full NPPES File: within a 30-minute drive of New York, NY: https://locationlists.com/find?dataset=us-healthcare-providers-full-nppes-file&near=New+York+NY&drive=30 - 100 retail stores within 25 miles of Los Angeles: https://locationlists.com/find?category=retail&near=Los+Angeles+CA&radius=25&total=100 - Dental practices in Richmond, VA: https://locationlists.com/find?dataset=dental-practice-list&city=Richmond&state=VA - Virginia federal contractors with over $5M in contract obligations: https://locationlists.com/find?dataset=virginia-federal-contractors&where=contract_obligations_total:gt:5000000 - STIHL dealers within 25 miles of zip 23219: https://locationlists.com/find?dataset=stihl-dealers&near=23219&radius=25 - STIHL dealers within a 30-minute drive of zip 23219: https://locationlists.com/find?dataset=stihl-dealers&near=23219&drive=30 Datasets by category: - Healthcare (257): every NPPES provider, Medicare-enrolled clinicians, nurse practitioners, pharmacists - Retail chains (178): Target, CVS, Walgreens, Aldi, Publix, Taco Bell - Federal contractors (148): every active SAM.gov registration, grant recipients - Industrial and equipment rental (99): Grainger, Fastenal, United Rentals, Sunbelt Rentals, Herc - Nonprofits (90): the full IRS file, grants awarded, churches - Bank branches (87): every FDIC-insured office - Equipment and tool dealers (40): STIHL, Husqvarna, DeWalt, Milwaukee, Makita - Furniture and mattresses (27): Ashley, Rooms To Go, Pottery Barn, Mattress Firm, Sleep Number - Restaurants (17): Dunkin', Waffle House, IHOP, Cracker Barrel - Hardware (14): Home Depot, Lowe's, Ace Hardware, Do It Best - Grill dealers (9): Traeger, Weber, Big Green Egg ## How to talk to the user - The user is usually a business person, not a developer. Explain every step in plain, non-technical language. Do not show them JSON, tool names or protocol terms unless they ask. - Always show the price and get a clear yes before you create a checkout link or pay for anything. - Searching, reading a dataset's details, sample rows and counts are free. Use them freely before talking about money. ## Comparing lists: nearest, within a distance, by area Comparing two lists by distance, or counting lists by area. Counts, summary numbers and up to 3 preview rows are free. Buying the rows costs the same per-row price as buying those rows directly. - How one list relates to another (MCP tool relate_locations, or /find with relate=): nearest (the 1 to 3 closest places from the other list, with miles), count_within (rank by how many of the other list are within a distance), within_any (places within a distance of any place on the other list), none_within (places with none of the other list within a distance). Give the other list with b. in front of its parameters and the distance as within=; order=desc on nearest ranks farthest first. A list's competitors are its own category minus itself: b.category=&b.exclude=. To buy the rows, pass the same arguments (with relate) to create_query_checkout for a card link, or to query_locations to pay in USDC. The file is the list's own columns plus the nearest place's name, address and miles, or the count. Example: https://locationlists.com/find?dataset=closed-bank-branches-us&state=OH&relate=nearest&k=1&b.dataset=bank-branches-us&b.state=OH - The same places on several lists (relate_locations with mode same_place or not_same_place, or /find with relate=same_place): the base list's places that are also on other lists, or not on them — the same street address and ZIP, or within 60 m sharing a name word. Give the other lists with b. c. d. in front of their parameters, also=b,c for the ones a place must be on and not_also=d for the ones it must not; every region of the overlap is counted free, with a 3-row preview naming the matching place. Example: https://locationlists.com/find?dataset=stihl-dealers&relate=same_place&also=b&b.dataset=husqvarna-dealers - Next best locations for a list (relate_locations with mode next_best, or /find with relate=next_best and state=): the sites in a state ranked by how well they match what the list's own locations typically have nearby (every place and brand that is near at least 15% of them and much more often than near a typical commercial spot), blended with an estimated market capture (a Huff model over the people in the site's ZIP and every competing location). Every site names the factors it matches. The analysis, the top 3 on the page and the top 50 in the JSON are free; the full ranked list is one CSV by card at the open-data per-row rate ($0.005 a site, one card fee, at most 10,000 sites), on the answer's /find/buy link. Available for the states whose place index is built, and the answer says when it is not. Example: https://locationlists.com/find?dataset=raising-canes-stores&state=VA&relate=next_best - Counts per county, ZIP, state or metro area (MCP tool count_by_area, or /find with areas=): up to 4 lists, and has / lacks to find areas that have one list but not another. Counts only, always free. area_where keeps only areas meeting a Census condition (county:population>500000), per= gives counts per that many residents, and per=&per_field= a rate over any Census count (per=1000&per_field=construction_establishments). - A Census fact about the area a place is in, on any list: area_where=: keeps rows whose area meets it (population, households, median household income, median age, growth since 2020, home values, and business establishments and employees in all and by NAICS sector — construction_establishments, health_care_employees…; the tool schemas list every attribute), and area_columns adds the facts as columns. The figure is the area's, not the place's, and adds nothing to the price. - The area's weather, the same way (NOAA, free): every month's and the year's high, low, mean temperature, precipitation and degree days as 1991–2020 normals and last year's actuals (july_high, may_precipitation, annual_temperature, annual_precipitation_2025…), the Palmer drought indices, storm events a year by type over the last ten years (tornado_events, hail_events, winter_storm_events, storm_property_damage…), and station normals — annual_snowfall, average_wind_speed, days over temperature and precipitation thresholds, growing and heating degree days at every base. Values accept units: county:july_high>95°F, zip:annual_precipitation>40 inches, county:average_wind_speed>12 mph. A ZIP code takes its county's weather. Example: https://locationlists.com/find?areas=county&dataset=bank-branches-us&state=VA&b.dataset=closed-bank-branches-us&b.state=VA&has=b - Cotenancy between two lists (MCP tool cotenancy, or /find with cotenancy=): the share of each list within that distance of the other, how many overlap, and the counties (or ZIPs, states, metros with by=) that have both, only the first or only the second. Counts only, always free. Example: https://locationlists.com/find?cotenancy=1&dataset=bank-branches-us&state=VA&b.dataset=closed-bank-branches-us&b.state=VA - Any US brand or kind of place works, not only our own lists: search_datasets also returns lists from Overture Maps open data (slugs overture-brand-… and overture-category-…, updated monthly, each labelled with how complete it is; kinds of place include independents). They work in every tool above at a low per-row price; our own list is preferred when both exist. - Distances are straight-line miles. Places without coordinates are left out and counted, never treated as far away. ## Optional: connect for repeat use or wallet payments No setup needed for a one-off question: open https://locationlists.com/find with the question as query parameters. Connecting is optional. ### 1. Connect The server is `https://locationlists.com/mcp`: Model Context Protocol over Streamable HTTP, no authentication, no API key, no sign-up. Pick the client you are running in. ### Claude Code Run this in a terminal, then restart the session so the tools load: ```bash claude mcp add --transport http locationlists https://locationlists.com/mcp ``` ### Claude (claude.ai, Claude Desktop, Cowork) You cannot add a connector yourself. Ask the user to do this, then start a new conversation: 1. Open Claude and go to Customize, then Connectors. 2. Click + and choose Add custom connector. 3. Name it LocationLists, paste https://locationlists.com/mcp as the URL, and click Add. ### Cursor Give the user this one-click install link: cursor://anysphere.cursor-deeplink/mcp/install?name=locationlists&config=eyJ1cmwiOiJodHRwczovL2xvY2F0aW9ubGlzdHMuY29tL21jcCJ9 Or add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in the project): ```json {"mcpServers":{"locationlists":{"url":"https://locationlists.com/mcp"}}} ``` ### VS Code Give the user this one-click install link: vscode:mcp/install?%7B%22name%22%3A%22locationlists%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Flocationlists.com%2Fmcp%22%7D Or add this to `.vscode/mcp.json`: ```json {"servers":{"locationlists":{"type":"http","url":"https://locationlists.com/mcp"}}} ``` ### ChatGPT You cannot add a connector yourself. Ask the user to do this in ChatGPT on the web, then start a new chat and pick LocationLists from the Developer mode menu: 1. In ChatGPT on the web, open Settings, then Security and login, and turn on Developer mode. This needs a paid plan. 2. Go to ChatGPT Plugins and click the + button. 3. Name it LocationLists, paste https://locationlists.com/mcp as the server URL, and choose no sign-in. ### Any other MCP client Add a remote server with transport Streamable HTTP (sometimes labelled "HTTP") at `https://locationlists.com/mcp`, no auth. ### No MCP client Any assistant that can open a web page needs no client at all: open https://locationlists.com/find links (see "Answer from a link first"). Plain HTTP works too. `POST https://locationlists.com/api/x402/query` takes the same JSON arguments as `query_locations` (one dataset, or `datasets` / `category` plus `total` for one combined answer); an unpaid request returns HTTP 402 with the exact price, and you retry with a signed x402 payment. Full spec: https://locationlists.com/openapi.json. Free JSON: https://locationlists.com/catalog.json and `https://locationlists.com/data/{slug}/sample.json`. ### Verify the connection Call `search_datasets` with `{"query": "dental"}`. A list of datasets with slugs and record counts means you are connected. If the tool is missing, the connector was not added or the session needs a restart. Either way, https://locationlists.com/find?search=dental returns the same list without a connector. ## 2. Use Every step here has a no-connector equivalent: https://locationlists.com/find?dataset= with the same filters as query parameters (see "Answer from a link first"). Follow this order. Every step here is free. 1. `search_datasets`: find the dataset by brand, location type or category. Note its `slug`. 2. `get_dataset`: read the record count, coverage, last-updated date and `columns`. Column names differ per dataset; use these exact names in filters. 3. `get_sample`: show the user real rows so they can judge the fields. 4. `count_locations`: count rows matching the user's filter (state, city, county, zip, `where` on any column, or `near` a place by straight-line miles (`radius_miles`) or by drive time (`drive_minutes`)). It returns the exact cost of fetching those rows and the price of the whole file. 5. `get_sample` again with the same filters: the match count plus up to 3 matching rows, so the user sees real locations in their area. Both `count_locations` and a filtered `get_sample` return `next`, which says exactly how to get every matching row and what it costs. Geography: filter by radius/city/zip with `count_locations` and `get_sample` before buying. `near` takes a place (`{"place": "Los Angeles, CA", "radius_miles": 25}`), a zip, or lat + lng. Near a place by straight-line miles (`radius_miles`) or by drive time (`drive_minutes`, 5 to 60), e.g. `{"zip": "23219", "drive_minutes": 30}` for everything within a 30-minute drive. Several datasets at once: each brand or chain is its own dataset, so for "100 retail stores around LA" pass `datasets` (a list of slugs) or `category` (for example "retail") instead of `dataset`, plus `total` (rows across all of them), to `count_locations`, `get_sample`, `create_query_checkout` and `query_locations`. You get one answer: counts per dataset, duplicates removed, up to 3 preview rows, one price, one payment and one CSV with a `source_dataset` column naming each row's dataset. Example arguments: `{"category":"retail","near":{"place":"Los Angeles, CA","radius_miles":25},"total":100}`. Worked example: dental practices in Austin, TX. ```json {"name": "search_datasets", "arguments": {"query": "dental"}} {"name": "get_dataset", "arguments": {"slug": "dental-practice-list"}} {"name": "get_sample", "arguments": {"slug": "dental-practice-list", "rows": 5}} {"name": "count_locations", "arguments": {"dataset":"dental-practice-list","state":"TX","city":"Austin"}} ``` Prices for this example today: 10 rows of US Dental Practices cost $0.04, 100 rows cost $0.28, and the whole file of 112,228 records is $149. Always quote the numbers `count_locations` returns, not these. ## 3. Buy Before any purchase: tell the user what they get (rows, filters, dataset) and the exact price, and wait for a yes. No connector: the https://locationlists.com/find answer for the same question carries the card Buy link; give the user that link. Pick the path: - **You have an x402 wallet** (a tool that signs x402 payments in USDC on Base): call `query_locations` for 100–1,000 matching rows per call (depending on row width; `count_locations` reports maxRowsPerCall), priced per row (page with `offset`), or `buy_dataset` for the whole file and a permanent download link. Past a few hundred rows the whole file is cheaper. Call without payment first: the result is the x402 quote with the exact amount. Retry with the signed payment in `params._meta["x402/payment"]`. - **No wallet** (most users): call `create_query_checkout` with the same filters to get a card payment link for just the matching rows, up to 10,000 rows. The data price is the same as paying by wallet; the card fee (2.9% + $0.30) is added on top and shown separately. For the whole file, call `create_checkout`. Give the user the link. After they pay, call `check_order` with the session id to get the CSV download link (it is also emailed). - `get_quote` prices several whole datasets at once and points out a bundle when one is cheaper. Money rules: - Failed or empty queries cost nothing. Payment settles only after rows are delivered. - Datasets under 5,000 records are sold only as the whole file ($9–$199 by record count). - Never claim a dataset is fresher than the last-updated date that get_dataset returns. Paying from Claude Desktop with a crypto wallet needs the user to install the wallet extension first: https://github.com/kylehawke-stack/x402-buyer-mcp/releases/latest. Claude cannot sign a payment on its own; the card link needs nothing installed. ## Can't find the list? If `search_datasets` (or https://locationlists.com/find?search= without a connector) finds nothing that fits, or the user wants a list we do not have, we may be able to add it. Requests are free. 1. Tell the user we do not have that list yet and ask whether they want to request it. 2. Ask whether they want to leave their email so we can tell them when it is ready. Use only an email the user gives you; never guess one. No email is fine. 3. Call `request_list` with `topic` (the list in their words, e.g. "Kubota dealers in Texas"), plus `email`, `use_case` and `details` (places, fields, timing) if they gave them. 4. Tell the user what the result says happens next. Do not promise a date. For a problem or suggestion (wrong data, something broken, pricing, an idea), ask first, then call `send_feedback`. If the user wants to pay later or from another device, ask for their email and call `email_quote` with the same arguments as `count_locations`: it emails a plain-English quote with a card checkout link. Free; nothing is charged. Results start with `answer` (and often `next`): plain words with a link, written for a business reader. `technicalDetails` is openly labelled reference information for developers and AI agents: tool names, JSON links and payment specifics. ## Limits The same limits apply to https://locationlists.com/find links, which run the same engine. - `get_sample`: up to 10 rows, or with filters the match count plus up to 3 matching rows. `query_locations`: 100–1,000 rows per call, by row width (maxRowsPerCall in `count_locations`). `create_query_checkout`: up to 10,000 rows per checkout. - Files over 80 MB cannot be filtered in one request; the answer says so and names the file size. A single-state version from `search_datasets`, when one exists, filters fine; otherwise buy the whole file. - Distance searches (`near`) work only on lists with map coordinates: `distanceSearch` in search results says which. The others filter by city, county or ZIP. - A place name that is not a Census place (a neighborhood, "downtown X", a misspelling) is matched to the closest Census place, county or metro in that state, and the answer says which one was used. - A small or empty answer says how many rows each filter removed and what the filtered column really holds; use that to fix the filter rather than telling the user the rows do not exist. - Large files can take several seconds to count or query. Checkout links stay valid for 24 hours. ## All tools Without a connector, the free tools' answers come from https://locationlists.com/find links (counts, preview rows, prices, search with search=). Free (14): - `search_datasets`: Find LocationLists datasets by brand, kind of business or industry (e.g. 'bobcat', 'restaurants', 'bank branches', 'dental practices', 'hardware stores'). - `relate_locations`: Free. How one set of places relates to another, by straight-line distance. - `count_by_area`: Free, counts only. Counts places per county / zip / state / metro for 1 to 4 labeled sets (each a dataset, datasets or category plus filters), and compares them: has (areas with at least one of every listed set) and lacks (areas with none of any listed set). - `cotenancy`: Free, counts only. How two sets of places sit together: the share of set a within radius_miles of set b and of b within radius_miles of a, how many places overlap, and the county / zip / state / metro areas that have both, only a, or only b (top 10 of each named). - `get_dataset`: Full record for one dataset: fields with descriptions, record and state counts, coverage, whether it can be searched by distance, advertised refresh cadence AND the real last-modified date of the file, FAQs, sample URL and the dataset's page on locationlists.com. - `count_locations`: Free. How many rows of one dataset match a filter — on geography AND any other column (e.g. nonprofits with revenue_amt gt 2000000, dealers with dealerClass eq 'Elite'). - `get_sample`: Free. Real rows from the live file, as JSON plus CSV text. - `request_list`: Ask LocationLists to add a list we do not have yet. - `send_feedback`: Send a message to the LocationLists team: wrong or missing data in a dataset, something that did not work, a pricing question, an idea, or anything else. - `email_quote`: Free. Emails the user a plain-English quote for exactly this request: how many rows match, the card price, a few of the matches and a card checkout link, so they can pay later, from any device, or forward it to whoever holds the card. - `get_quote`: Line-item prices and total for a list of dataset slugs. - `create_checkout`: Opens a Stripe Checkout session for one dataset and returns the payment URL plus the session id. - `check_order`: Given a Stripe Checkout session id (cs_…), reports whether it is paid and, if so, returns the permanent download link for the CSV. - `create_query_checkout`: For buyers paying by card (no wallet needed): opens a Stripe Checkout for just the rows of one dataset that match a filter, and returns the payment URL to give the user. Paid (2): - `query_locations`: Return matching rows from one dataset, filtered on ANY of its columns — state/city/county/zip shortcuts plus `where` conditions with numeric comparisons (e.g. [{field:"revenue_amt",op:"gt",value:2000000}]), sorted with `order_by` and paged with `offset`. - `buy_dataset`: Buy an ENTIRE dataset outright and get a permanent download link for the CSV. ## Links - Ask any question with a link, no connector: https://locationlists.com/find - Setup page for people: https://locationlists.com/agents - Site summary for assistants: https://locationlists.com/llms.txt - HTTP API spec: https://locationlists.com/openapi.json - Catalog as JSON: https://locationlists.com/catalog.json - Support: kyle@locationlists.com