yellowpages-mcp

# Yellow Pages MCP Server

<!-- mcp-name: com.hasdata/yellowpages -->

A hosted Model Context Protocol (MCP) server that gives Claude, Cursor, Windsurf and any other MCP client two read-only Yellow Pages tools. Search local businesses by keyword and location, then read one listing in full with its phone, hours, services and photos, both as structured JSON, with nothing to host.

It reads public Yellow Pages listings that a signed-out visitor can see, on `yellowpages.com` and `yellowpages.ca`.

**1,000 free credits every month, no card required**, which is 100 Yellow Pages calls at the 10-credit rate.

```
https://mcp.hasdata.com/api/mcp?apis=yellowpages
```

[![Glama score](https://glama.ai/mcp/servers/HasData/yellowpages-mcp/badges/score.svg)](https://glama.ai/mcp/servers/HasData/yellowpages-mcp)
[![tool contract](https://github.com/HasData/yellowpages-mcp/actions/workflows/contract.yml/badge.svg)](https://github.com/HasData/yellowpages-mcp/actions/workflows/contract.yml)
[![MCP](https://img.shields.io/badge/MCP-remote%20%7C%20streamable%20HTTP-6366f1?style=flat-square)](https://mcp.hasdata.com/api/mcp?apis=yellowpages)
[![Tools](https://img.shields.io/badge/tools-2-10b981?style=flat-square)](#tools)
[![npm](https://img.shields.io/npm/v/@hasdata/yellowpages-mcp?style=flat-square&logo=npm&label=npm&color=cb3837)](https://www.npmjs.com/package/@hasdata/yellowpages-mcp)
[![PyPI](https://img.shields.io/pypi/v/hasdata-yellowpages-mcp?style=flat-square&logo=pypi&logoColor=white&label=PyPI&color=3775a9)](https://pypi.org/project/hasdata-yellowpages-mcp/)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

## Contents

- [What you need](#what-you-need)
- [Quick start](#quick-start)
- [Example prompts](#example-prompts)
- [Tools](#tools)
- [Errors and failure paths](#errors-and-failure-paths)
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
- [Tool selection](#tool-selection)
- [How it compares](#how-it-compares)
- [FAQ](#faq)
- [HasData links](#hasdata-links)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## What you need

An MCP client and a HasData API key from the [dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=yellowpages-mcp), free to create with no card, and the free tier covers about 100 calls a month at the 10-credit rate. This is a remote server, so the simplest path is a URL and an `x-api-key` header, with no container to run. A client that only speaks stdio reaches it through a thin launcher, published as `@hasdata/yellowpages-mcp` on npm and `hasdata-yellowpages-mcp` on PyPI, shown below.

## Quick start

The server URL is the same for every client. We run it hands-on in Claude Code and Claude Desktop. The other blocks follow each client's own documented format for a remote server.

| Field | Value |
| :--- | :--- |
| URL | `https://mcp.hasdata.com/api/mcp?apis=yellowpages` |
| Transport | HTTP, streamable |
| Auth header | `x-api-key: HASDATA_API_KEY` |

Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --transport http yellowpages "https://mcp.hasdata.com/api/mcp?apis=yellowpages" \
  --header "x-api-key: HASDATA_API_KEY"
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings, then Connectors, then Add custom connector, then paste `https://mcp.hasdata.com/api/mcp?apis=yellowpages` and sign in.

For the config-file route, Claude Desktop loads only local (stdio) servers, so it reaches a remote server through a stdio launcher. The `@hasdata/yellowpages-mcp` package is that launcher, and it reads the key from the environment. Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "yellowpages": {
      "command": "npx",
      "args": ["-y", "@hasdata/yellowpages-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

For Python instead of Node, swap the launcher for the PyPI package, which `uvx` runs without a manual install:

```json
{
  "mcpServers": {
    "yellowpages": {
      "command": "uvx",
      "args": ["hasdata-yellowpages-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Cursor</b></summary>

`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:

```json
{
  "mcpServers": {
    "yellowpages": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=yellowpages",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

`~/.codeium/windsurf/mcp_config.json`. Windsurf calls the field `serverUrl`, not `url`:

```json
{
  "mcpServers": {
    "yellowpages": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=yellowpages",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>VS Code</b></summary>

`.vscode/mcp.json` in the workspace:

```json
{
  "servers": {
    "yellowpages": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=yellowpages",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

## Example prompts

Each of these lands on one tool, or on two in sequence when the second needs the URL the first returns.

- Find plumbers in Austin, TX and rank them by rating against review count.
- List every HVAC contractor in this zipcode with a phone number and hours.
- Which of these businesses have been trading for more than 20 years?
- Read this Yellow Pages listing and tell me which brands they service.
- Pull page 2 and 3 of roofers in Austin and merge them into one list.
- Sort dentists in this city by average rating rather than by relevance.

A prompt that names a niche and a city goes to the search tool. Reading services, brands and payment methods takes a second call per business, so a prospect list wants the search tool and an enrichment pass wants the place tool.

## Tools

Two tools, 10 credits per successful call.

### Get Yellow Pages search results

[`hasdata_yellowpages_search_getSearchResults`](https://docs.hasdata.com/apis/yellowpages/search?utm_source=github&utm_medium=syndication&utm_campaign=yellowpages-mcp)

A page of businesses for a keyword in a place, 30 to a page.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `keyword` | string | yes | What to search for, such as `plumber` |
| `location` | string | yes | Where to search, such as `Austin, TX` |
| `sort` | string | | `default`, `distance`, `averageRating` or `name` |
| `domain` | string | | `www.yellowpages.com` or `www.yellowpages.ca` |
| `page` | number | | Result page, starting at 1 |

Returns `searchInformation` with the echoed query and `totalResults`, an `organicResults` array, and `pagination` with `currentPage`, `totalPages`, `perPage`, `nextPageUrl` and `otherPageUrls`.

Almost every field on a result is optional, because Yellow Pages shows what each business paid for or filled in. Across the 30 results in the sample, `title`, `phone`, `url`, `categories`, `country` and `position` arrived on all of them, `address` on 22, `rating` and `reviews` on 11, and `contactUs` on 5. Read defensively rather than assuming a shape.

```json
{
  "position": 2,
  "title": "Clarke Kent Plumbing",
  "url": "https://www.yellowpages.com/austin-tx/mip/clarke-kent-plumbing-10674347?lid=1002194068759",
  "phone": "(512) 766-0970",
  "address": "1408 W Ben White Blvd",
  "city": "Austin",
  "region": "TX",
  "zipcode": "78704",
  "country": "US",
  "website": "http://www.clarkekentplumbing.com",
  "directions": "https://www.yellowpages.com/listings/1002194068759/directions",
  "categories": ["Plumbers", "Plumbing-Drain & Sewer Cleaning"],
  "rating": 2.87,
  "reviews": 15,
  "workingHours": ["Mo-Fr 09:00-17:00"],
  "openState": "open now",
  "badges": ["40 Years in Business", "1 Year with Yellow Pages"]
}
```

### Get Yellow Pages place details

[`hasdata_yellowpages_place_getPlaceDetails`](https://docs.hasdata.com/apis/yellowpages/place?utm_source=github&utm_medium=syndication&utm_campaign=yellowpages-mcp)

One listing in full, by its Yellow Pages URL.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `url` | string | yes | The listing URL, as the search tool returns it |

Returns four blocks rather than one flat object.

`overview` repeats the name, location, phone, hours, badges and website, and adds `paymentAccepted` and a `breadcrumbs` array showing where the listing sits in the Yellow Pages taxonomy. `ratings` holds the star rating. `details` holds the long-form copy the business wrote. `images` is an array of photo URLs.

The `details` block is where the enrichment value sits, and it arrives as comma-joined text rather than as arrays. `generalInfo` is the business description, `servicesProducts` the service list, `brands` the brands they carry, `paymentMethod` the payment types and `categories` the full category list as one string.

```json
{
  "overview": {
    "title": "ARS Rescue Rooter",
    "phone": "(833) 947-9225",
    "city": "Austin",
    "region": "TX",
    "zipcode": "78754",
    "workingHours": ["Mo-Su"],
    "openState": "Open 24 hours",
    "paymentAccepted": "visa, amex, master card",
    "badges": ["1 Year with Yellow Pages"],
    "breadcrumbs": ["TX", "Austin", "Building Contractors", "Plumbers"]
  },
  "ratings": { "rating": 3.5 },
  "details": {
    "generalInfo": "ARS/Rescue Rooter has a proven track record of providing reliable, long-lasting repair services...",
    "servicesProducts": "Air Conditioner Repair and Replacement, Air Duct Repair and Replacement, Air Filter Installation...",
    "brands": "Goodman, Mitsubishi, Bosch, Diakin, Bradford White, April Aire Indoor Air Quality",
    "paymentMethod": "visa, amex, master card"
  },
  "images": ["https://i4.ypcdn.com/blob/ce73451958465ab47dd7be4