yellowpages-mcp

Purpose

yellowpages-mcp is a hosted Model Context Protocol (MCP) server that lets AI clients (such as Claude, Cursor, Windsurf) programmatically access Yellow Pages' public local business information. It is aimed at scenarios such as lead generation, business research, and competitive or coverage analysis, turning work that would otherwise require a browser or scraping library into JSON data that agents can directly reason over.

Main capabilities

The server exposes only two read-only tools:

1. hasdata_yellowpages_search_getSearchResults: returns one page of businesses by keyword and location, 30 per page. Returns searchInformation(echoes the query and totalResults）、organicResults array, as well as pagination(including currentPage、totalPages、perPage、nextPageUrl、otherPageUrls). Almost all result fields are optional: among the 30 results in the sample, title、phone、url、categories、country、position are all present,address appears in 22,rating and reviews appear in 11, andcontactUs appears in 5.

2. hasdata_yellowpages_place_getPlaceDetails: returns a single full listing by Yellow Pages URL, containing four blocks:overview(name, location, phone, business hours, badges, website, plus attached paymentAccepted and breadcrumbs category path arrays),ratings(star rating),details(long-form text written by the business, in which generalInfo、servicesProducts、brands、paymentMethod、categories are all comma-joined strings rather than arrays),images(array of photo URLs). Thedetails block is the main source of value-added information.

In addition, the server provides 2 resources, corresponding to two parameters that accept fixed value lists, with URI format hasdata://yellowpages/<parameter>; reading does not consume credits, and no API key is required to read them.

How to use

You need an MCP client and a HasData API key (created in the dashboard, free and no credit card required). This is a remote server, and the simplest way is to use the URL plus the x-api-key request header, with no need to run a container. Clients that support only stdio can access it through a thin launcher, which has been published as @hasdata/yellowpages-mcp on npm and hasdata-yellowpages-mcpon PyPI.

The server URL is the same for all clients. Clients that support OAuth can add the same URL as a connector and log in, without putting a key in a configuration file: Settings → Connectors → Add custom connector, paste https://mcp.hasdata.com/mcp?apis=yellowpages and log in.

Claude Desktop only loads local (stdio) servers, so it accesses the remote server through the stdio launcher. The@hasdata/yellowpages-mcp package is that launcher, and reads the key from an environment variable. Add the configuration in claude_desktop_config.json . If using Python, you can replace the launcher with the PyPI package and run it with uvx without manual installation. Cursor uses ~/.cursor/mcp.json(global) or .cursor/mcp.json(single project); Windsurf uses ~/.codeium/windsurf/mcp_config.json, and the field name is serverUrl rather than url; VS Code uses the one in the workspace .vscode/mcp.json.

Example prompts: find plumbers in Austin, TX and sort by rating relative to review count; list all HVAC contractors in that ZIP code with phone and business hours; read a given Yellow Pages listing and explain the brands it serves. Prompts that name a specific industry and city will call the search tool; reading services, brands, and payment methods requires a second call for each merchant.

Use cases

• Generate lead lists (a single search tool call returns name, phone, address, category, business hours, badges, and, when shown by Yellow Pages, rating and review count)
• Merchant information enrichment (the place tool supplements description, service list, brands, and photos, consuming one call per merchant)
• Server-side sorting by average rating, etc. (using the sort: averageRating parameter)
• Coverage statistics, ratings comparison, agency opportunity research

Restrictions and caveats

• Billing: each successful Yellow Pages tool call consumes 10 credits. Response size does not affect the price. Non-200 responses are not billed, but calls that successfully return empty results are still billed.
• Free quota: 1,000 credits per month (no credit card required), roughly equivalent to 100 calls, renewed with the billing cycle.
• Paid plans: starting at $59/month for 200,000 credits (20,000 calls), with unit price decreasing as volume increases. See the pricing page for current figures.
• Concurrency limits: 1 concurrent request for Free, 5 for Startup, 15 for Basic, and 50 to 500 for the Growth tier. Unattended scenarios require backoff and retry for 429.
• Data reliability: except for name, phone, URL, and category, almost all fields are optional and should be read defensively.
• Review count: should be read from search results; the place tool's ratings.reviews was equal to ratings.ratingin all listings checked, and does not include the count.
• ratings may be completely missing rather than an empty object.
• details field is a comma-joined string, andcategories has different types between the two tools (an array in search results, a string in details).
• website sometimes points to a Yellow Pages tracking URL of its own; check the host before storing or using it.
• Years in business is a badge (badges) rather than a field; read the text rather than the first number.
• Street address is not guaranteed to exist and must be constructed from fields such as city、region、zipcode .
• openState is a snapshot at the time of the call, whileworkingHours is the persistent field.
• Pagination is URL-based, and cost grows with the number of pages, so keywords should be narrowed first.
• Coverage: yellowpages.com in the United States and yellowpages.ca in Canada, switched via the domain parameter.
• Compliance: listings are business records, but using the collected phone numbers for calls and text messages is separately regulated by rules such as the TCPA and FTC telemarketing rules; listings for sole proprietors may contain personal names and mobile numbers, constituting personal data.
• There is no official Yellow Pages MCP server or public API. This server is maintained by HasData and is not affiliated with, endorsed by, or sponsored by the Yellow Pages brand.

Testing and licensing

The tests in the repository assert the tool contract (parameters, names, required parameters, descriptions, sort options, whether keys are accepted), and one of the tests actually calls the tool and consumes 10 credits; the contract suite runs on a weekly schedule. The project uses the MIT license.