yelp-mcp

# Yelp MCP Server

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

A hosted Model Context Protocol (MCP) server that gives Claude, Cursor, Windsurf and any other MCP client three read-only Yelp tools. Search businesses by keyword and location, read one business in full, and page through its complete review feed, all as structured JSON, with no Yelp Fusion key and nothing to host.

It reads public Yelp pages that a signed-out visitor can see, on any of the 41 regional domains.

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

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

[![Glama score](https://glama.ai/mcp/servers/HasData/yelp-mcp/badges/score.svg)](https://glama.ai/mcp/servers/HasData/yelp-mcp)
[![tool contract](https://github.com/HasData/yelp-mcp/actions/workflows/contract.yml/badge.svg)](https://github.com/HasData/yelp-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=yelp)
[![Tools](https://img.shields.io/badge/tools-3-10b981?style=flat-square)](#tools)
[![npm](https://img.shields.io/npm/v/@hasdata/yelp-mcp?style=flat-square&logo=npm&label=npm&color=cb3837)](https://www.npmjs.com/package/@hasdata/yelp-mcp)
[![PyPI](https://img.shields.io/pypi/v/hasdata-yelp-mcp?style=flat-square&logo=pypi&logoColor=white&label=PyPI&color=3775a9)](https://pypi.org/project/hasdata-yelp-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=yelp-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/yelp-mcp` on npm and `hasdata-yelp-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=yelp` |
| 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 yelp "https://mcp.hasdata.com/api/mcp?apis=yelp" \
  --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=yelp` 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/yelp-mcp` package is that launcher, and it reads the key from the environment. Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "yelp": {
      "command": "npx",
      "args": ["-y", "@hasdata/yelp-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": {
    "yelp": {
      "command": "uvx",
      "args": ["hasdata-yelp-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": {
    "yelp": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=yelp",
      "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": {
    "yelp": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=yelp",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

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

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

```json
{
  "servers": {
    "yelp": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=yelp",
      "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 an identifier the first returns.

- Find coffee roasteries in Austin, TX and rank them by rating against review count.
- Pull the hours, phone and website for the Yelp business `desnudo-coffee-austin`.
- Read every one-star and two-star review of this business and group the complaints by theme.
- Which dishes does Yelp list as popular for this place, and what do reviewers say about them?
- Compare the rating distribution of these three competitors in the same neighborhood.
- Show me the reviews Yelp does not recommend for this business and how they differ from the recommended ones.

A prompt that names a business rather than a Yelp ID takes two calls, one search to resolve the ID and one place or reviews lookup to read it. The search tool returns both `placeId` and `placeAlias`, and either one works as the `placeId` argument to the place tool.

## Tools

Three tools, 10 credits per successful call. Every tool accepts `domain` to switch country, one of 41 values, from `www.yelp.com` through the European, Asian and Latin American sites, including the language-specific variants such as `fr.yelp.ca` and `zh.yelp.com.hk`.

### Get Yelp search results

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

A page of businesses for a keyword in a place.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `keyword` | string | yes | What to search for, such as `coffee` |
| `location` | string | yes | Where to search, such as `Austin, TX` |
| `l` | string | | Map bounding box instead of a radius, as `g:lon1,lat1,lon2,lat2` |
| `domain` | string | | Yelp site, defaults to `www.yelp.com` |
| `start` | number | | Result offset, stepping by 10 |

Returns `searchInformation` with the echoed `keyword`, `location` and `totalResults`, an `ads` array of paid placements, an `organicResults` array, and `pagination` with `currentPage`, `perPage`, `totalPages`, `nextPageUrl` and `otherPagesUrls`.

The two result arrays are not the same shape. An organic result carries `position` and `streetAddress`, while an ad carries neither and adds `phone` and a `highlights` array of the badges Yelp shows advertisers. Merging the arrays without checking which one a business came from turns paid placement into rank.

```json
{
  "position": 2,
  "placeId": "oiJ7QuhhpsEpe9zFTZF0bA",
  "placeAlias": "desnudo-coffee-austin",
  "url": "https://www.yelp.com/biz/desnudo-coffee-austin",
  "title": "Desnudo Coffee",
  "streetAddress": "2505 Webberville Rd, Austin",
  "price": "$$",
  "categories": [{ "title": "Coffee Roasteries", "url": "https://www.yelp.com/search?find_desc=Coffee+Roasteries&amp;find_loc=Austin%2C+TX" }],
  "snippet": "My favorite coffee shop to go to ever! Everyone must go. [[HIGHLIGHT]]Great coffee[[ENDHIGHLIGHT]], great vibes,great customer...",
  "rating": 4.7,
  "reviews": 347,
  "thumbnail": "https://s3-media0.fl.yelpcdn.com/bphoto/0nE_IcbRiyxrw3kk2z6owg/ls.jpg",
  "allImagesUrl": "https://www.yelp.com/biz_photos/oiJ7QuhhpsEpe9zFTZF0bA"
}
```

### Get Yelp place details

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

One business in full.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `placeId` | string | yes | A Yelp ID such as `oiJ7QuhhpsEpe9zFTZF0bA`, or an alias such as `desnudo-coffee-austin` |
| `domain` | string | | Yelp site, defaults to `www.yelp.com` |

Returns a `placeResult` object with `name`, `url`, `address`, `neighborhoods`, `country`, `phone`, `website`, `price`, `categories`, `rating`, `reviews`, `isClaimed` and `isClaimable`, an `operationHours` object holding a week of `hours` plus `today`, a `features` array, a `menu` object with `popularDishes`, a `faqs` array of questions Yelp readers asked and answered, a `reviewHighlights` array of the phrases Yelp pins to the top of the page, an `images` array, and `businessMap`, a static map image URL.

`features` is the amenities block, and each entry carries a `title` and an `isActive` flag, so a false entry is Yelp stating the amenity is absent rather than unknown. That difference matters when you filter, because dropping the false entries and dropping the missing ones are not the same query.

```json
{
  "name": "Desnudo Coffee",
  "url": "https://www.yelp.com/biz/desnudo-coffee-austin",
  "address": "2505 Webberville Rd Austin, TX 78702",
  "neighborhoods": "East Austin",
  "country": "US",
  "phone": "(424) 400-1857",
  "website": "http://www.desnudocoffee.com",
  "price": "$$",
  "categories": ["Coffee Roasteries"],
  "rating": 4.7,
  "reviews": 347,
  "isClaimed": true,
  "isClaimable": false,
  "operationHours": { "hours": [{ "day": "Mon", "hours": ["7:00 AM - 2:00 PM"] }] },
  "features": [