@hasdata/yelp-mcp 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +425 -0
- package/index.mjs +24 -0
- package/package.json +41 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 HasData
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,425 @@
|
|
|
1
|
+
# Yelp MCP Server
|
|
2
|
+
|
|
3
|
+
<!-- mcp-name: com.hasdata/yelp -->
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
It reads public Yelp pages that a signed-out visitor can see, on any of the 41 regional domains.
|
|
8
|
+
|
|
9
|
+
**1,000 free credits every month, no card required**, which is 100 Yelp calls at the 10-credit rate.
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
https://mcp.hasdata.com/api/mcp?apis=yelp
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
[](https://glama.ai/mcp/servers/HasData/yelp-mcp)
|
|
16
|
+
[](https://github.com/HasData/yelp-mcp/actions/workflows/contract.yml)
|
|
17
|
+
[](https://mcp.hasdata.com/api/mcp?apis=yelp)
|
|
18
|
+
[](#tools)
|
|
19
|
+
[](https://www.npmjs.com/package/@hasdata/yelp-mcp)
|
|
20
|
+
[](https://pypi.org/project/hasdata-yelp-mcp/)
|
|
21
|
+
[](LICENSE)
|
|
22
|
+
|
|
23
|
+
## Contents
|
|
24
|
+
|
|
25
|
+
- [What you need](#what-you-need)
|
|
26
|
+
- [Quick start](#quick-start)
|
|
27
|
+
- [Example prompts](#example-prompts)
|
|
28
|
+
- [Tools](#tools)
|
|
29
|
+
- [Errors and failure paths](#errors-and-failure-paths)
|
|
30
|
+
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
|
|
31
|
+
- [Tool selection](#tool-selection)
|
|
32
|
+
- [How it compares](#how-it-compares)
|
|
33
|
+
- [FAQ](#faq)
|
|
34
|
+
- [HasData links](#hasdata-links)
|
|
35
|
+
- [Development](#development)
|
|
36
|
+
- [Contributing](#contributing)
|
|
37
|
+
- [License](#license)
|
|
38
|
+
|
|
39
|
+
## What you need
|
|
40
|
+
|
|
41
|
+
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.
|
|
42
|
+
|
|
43
|
+
## Quick start
|
|
44
|
+
|
|
45
|
+
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.
|
|
46
|
+
|
|
47
|
+
| Field | Value |
|
|
48
|
+
| :--- | :--- |
|
|
49
|
+
| URL | `https://mcp.hasdata.com/api/mcp?apis=yelp` |
|
|
50
|
+
| Transport | HTTP, streamable |
|
|
51
|
+
| Auth header | `x-api-key: HASDATA_API_KEY` |
|
|
52
|
+
|
|
53
|
+
Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.
|
|
54
|
+
|
|
55
|
+
<details>
|
|
56
|
+
<summary><b>Claude Code</b></summary>
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
claude mcp add --transport http yelp "https://mcp.hasdata.com/api/mcp?apis=yelp" \
|
|
60
|
+
--header "x-api-key: HASDATA_API_KEY"
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
</details>
|
|
64
|
+
|
|
65
|
+
<details>
|
|
66
|
+
<summary><b>Claude Desktop</b></summary>
|
|
67
|
+
|
|
68
|
+
Settings, then Connectors, then Add custom connector, then paste `https://mcp.hasdata.com/api/mcp?apis=yelp` and sign in.
|
|
69
|
+
|
|
70
|
+
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`:
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"mcpServers": {
|
|
75
|
+
"yelp": {
|
|
76
|
+
"command": "npx",
|
|
77
|
+
"args": ["-y", "@hasdata/yelp-mcp"],
|
|
78
|
+
"env": { "HASDATA_API_KEY": "YOUR_KEY" }
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
For Python instead of Node, swap the launcher for the PyPI package, which `uvx` runs without a manual install:
|
|
85
|
+
|
|
86
|
+
```json
|
|
87
|
+
{
|
|
88
|
+
"mcpServers": {
|
|
89
|
+
"yelp": {
|
|
90
|
+
"command": "uvx",
|
|
91
|
+
"args": ["hasdata-yelp-mcp"],
|
|
92
|
+
"env": { "HASDATA_API_KEY": "YOUR_KEY" }
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
</details>
|
|
99
|
+
|
|
100
|
+
<details>
|
|
101
|
+
<summary><b>Cursor</b></summary>
|
|
102
|
+
|
|
103
|
+
`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
{
|
|
107
|
+
"mcpServers": {
|
|
108
|
+
"yelp": {
|
|
109
|
+
"url": "https://mcp.hasdata.com/api/mcp?apis=yelp",
|
|
110
|
+
"headers": { "x-api-key": "HASDATA_API_KEY" }
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
</details>
|
|
117
|
+
|
|
118
|
+
<details>
|
|
119
|
+
<summary><b>Windsurf</b></summary>
|
|
120
|
+
|
|
121
|
+
`~/.codeium/windsurf/mcp_config.json`. Windsurf calls the field `serverUrl`, not `url`:
|
|
122
|
+
|
|
123
|
+
```json
|
|
124
|
+
{
|
|
125
|
+
"mcpServers": {
|
|
126
|
+
"yelp": {
|
|
127
|
+
"serverUrl": "https://mcp.hasdata.com/api/mcp?apis=yelp",
|
|
128
|
+
"headers": { "x-api-key": "HASDATA_API_KEY" }
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
</details>
|
|
135
|
+
|
|
136
|
+
<details>
|
|
137
|
+
<summary><b>VS Code</b></summary>
|
|
138
|
+
|
|
139
|
+
`.vscode/mcp.json` in the workspace:
|
|
140
|
+
|
|
141
|
+
```json
|
|
142
|
+
{
|
|
143
|
+
"servers": {
|
|
144
|
+
"yelp": {
|
|
145
|
+
"type": "http",
|
|
146
|
+
"url": "https://mcp.hasdata.com/api/mcp?apis=yelp",
|
|
147
|
+
"headers": { "x-api-key": "HASDATA_API_KEY" }
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
</details>
|
|
154
|
+
|
|
155
|
+
## Example prompts
|
|
156
|
+
|
|
157
|
+
Each of these lands on one tool, or on two in sequence when the second needs an identifier the first returns.
|
|
158
|
+
|
|
159
|
+
- Find coffee roasteries in Austin, TX and rank them by rating against review count.
|
|
160
|
+
- Pull the hours, phone and website for the Yelp business `desnudo-coffee-austin`.
|
|
161
|
+
- Read every one-star and two-star review of this business and group the complaints by theme.
|
|
162
|
+
- Which dishes does Yelp list as popular for this place, and what do reviewers say about them?
|
|
163
|
+
- Compare the rating distribution of these three competitors in the same neighborhood.
|
|
164
|
+
- Show me the reviews Yelp does not recommend for this business and how they differ from the recommended ones.
|
|
165
|
+
|
|
166
|
+
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.
|
|
167
|
+
|
|
168
|
+
## Tools
|
|
169
|
+
|
|
170
|
+
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`.
|
|
171
|
+
|
|
172
|
+
### Get Yelp search results
|
|
173
|
+
|
|
174
|
+
[`hasdata_yelp_search_getSearchResults`](https://docs.hasdata.com/apis/yelp/search?utm_source=github&utm_medium=syndication&utm_campaign=yelp-mcp)
|
|
175
|
+
|
|
176
|
+
A page of businesses for a keyword in a place.
|
|
177
|
+
|
|
178
|
+
| Parameter | Type | Required | Notes |
|
|
179
|
+
| :--- | :--- | :--- | :--- |
|
|
180
|
+
| `keyword` | string | yes | What to search for, such as `coffee` |
|
|
181
|
+
| `location` | string | yes | Where to search, such as `Austin, TX` |
|
|
182
|
+
| `l` | string | | Map bounding box instead of a radius, as `g:lon1,lat1,lon2,lat2` |
|
|
183
|
+
| `domain` | string | | Yelp site, defaults to `www.yelp.com` |
|
|
184
|
+
| `start` | number | | Result offset, stepping by 10 |
|
|
185
|
+
|
|
186
|
+
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`.
|
|
187
|
+
|
|
188
|
+
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.
|
|
189
|
+
|
|
190
|
+
```json
|
|
191
|
+
{
|
|
192
|
+
"position": 2,
|
|
193
|
+
"placeId": "oiJ7QuhhpsEpe9zFTZF0bA",
|
|
194
|
+
"placeAlias": "desnudo-coffee-austin",
|
|
195
|
+
"url": "https://www.yelp.com/biz/desnudo-coffee-austin",
|
|
196
|
+
"title": "Desnudo Coffee",
|
|
197
|
+
"streetAddress": "2505 Webberville Rd, Austin",
|
|
198
|
+
"price": "$$",
|
|
199
|
+
"categories": [{ "title": "Coffee Roasteries", "url": "https://www.yelp.com/search?find_desc=Coffee+Roasteries&find_loc=Austin%2C+TX" }],
|
|
200
|
+
"snippet": "My favorite coffee shop to go to ever! Everyone must go. [[HIGHLIGHT]]Great coffee[[ENDHIGHLIGHT]], great vibes,great customer...",
|
|
201
|
+
"rating": 4.7,
|
|
202
|
+
"reviews": 347,
|
|
203
|
+
"thumbnail": "https://s3-media0.fl.yelpcdn.com/bphoto/0nE_IcbRiyxrw3kk2z6owg/ls.jpg",
|
|
204
|
+
"allImagesUrl": "https://www.yelp.com/biz_photos/oiJ7QuhhpsEpe9zFTZF0bA"
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### Get Yelp place details
|
|
209
|
+
|
|
210
|
+
[`hasdata_yelp_place_getPlaceDetails`](https://docs.hasdata.com/apis/yelp/place?utm_source=github&utm_medium=syndication&utm_campaign=yelp-mcp)
|
|
211
|
+
|
|
212
|
+
One business in full.
|
|
213
|
+
|
|
214
|
+
| Parameter | Type | Required | Notes |
|
|
215
|
+
| :--- | :--- | :--- | :--- |
|
|
216
|
+
| `placeId` | string | yes | A Yelp ID such as `oiJ7QuhhpsEpe9zFTZF0bA`, or an alias such as `desnudo-coffee-austin` |
|
|
217
|
+
| `domain` | string | | Yelp site, defaults to `www.yelp.com` |
|
|
218
|
+
|
|
219
|
+
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.
|
|
220
|
+
|
|
221
|
+
`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.
|
|
222
|
+
|
|
223
|
+
```json
|
|
224
|
+
{
|
|
225
|
+
"name": "Desnudo Coffee",
|
|
226
|
+
"url": "https://www.yelp.com/biz/desnudo-coffee-austin",
|
|
227
|
+
"address": "2505 Webberville Rd Austin, TX 78702",
|
|
228
|
+
"neighborhoods": "East Austin",
|
|
229
|
+
"country": "US",
|
|
230
|
+
"phone": "(424) 400-1857",
|
|
231
|
+
"website": "http://www.desnudocoffee.com",
|
|
232
|
+
"price": "$$",
|
|
233
|
+
"categories": ["Coffee Roasteries"],
|
|
234
|
+
"rating": 4.7,
|
|
235
|
+
"reviews": 347,
|
|
236
|
+
"isClaimed": true,
|
|
237
|
+
"isClaimable": false,
|
|
238
|
+
"operationHours": { "hours": [{ "day": "Mon", "hours": ["7:00 AM - 2:00 PM"] }] },
|
|
239
|
+
"features": [
|
|
240
|
+
{ "title": "Offers delivery", "isActive": true },
|
|
241
|
+
{ "title": "ADA-compliant restroom", "isActive": false }
|
|
242
|
+
],
|
|
243
|
+
"menu": {
|
|
244
|
+
"section": "Popular Drinks",
|
|
245
|
+
"popularDishes": [{ "name": "Brown Sugar Miso Latte", "rating": 4.7, "reviews": 113, "photos": 71 }]
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
### Get Yelp place reviews
|
|
251
|
+
|
|
252
|
+
[`hasdata_yelp_reviews_getPlaceReviews`](https://docs.hasdata.com/apis/yelp/reviews?utm_source=github&utm_medium=syndication&utm_campaign=yelp-mcp)
|
|
253
|
+
|
|
254
|
+
The review feed of one business, in full text, with sorting, filtering and pagination.
|
|
255
|
+
|
|
256
|
+
| Parameter | Type | Required | Notes |
|
|
257
|
+
| :--- | :--- | :--- | :--- |
|
|
258
|
+
| `placeId` | string | yes | The Yelp ID of the business |
|
|
259
|
+
| `domain` | string | | Yelp site, defaults to `www.yelp.com` |
|
|
260
|
+
| `sortBy` | string | | `relevanceDesc` (default), `dateDesc`, `dateAsc`, `ratingDesc`, `ratingAsc` or `elitesDesc` |
|
|
261
|
+
| `rating` | string | | Keep only these star ratings, such as `5` or `1,2` |
|
|
262
|
+
| `query` | string | | Free-text search inside the reviews |
|
|
263
|
+
| `languageCode` | string | | Two-letter language of the reviews, defaults to `en` |
|
|
264
|
+
| `notRecommended` | boolean | | Return the feed Yelp filters out instead of the recommended one |
|
|
265
|
+
| `start` | number | | Offset, stepping by `num` |
|
|
266
|
+
| `num` | number | | Page size, 49 at most, and 49 by default |
|
|
267
|
+
| `nextPageToken` | string | | Cursor taken verbatim from the previous response |
|
|
268
|
+
|
|
269
|
+
Returns `searchInformation` with the business name, alias, URL, `totalResults`, `rating`, a `reviewCountsByRating` array and a `reviewCountsByLanguage` breakdown, a `pagination` object, and a `reviews` array.
|
|
270
|
+
|
|
271
|
+
Each review carries `position`, `id`, `link`, a `user` object, a `comment` object holding `text` and its detected `language`, `date`, `rating`, and, when the reviewer attached them, `photos`, `videos` and `reactions`. The `user` object reports `name`, `userId`, `address`, lifetime `reviews`, `friends` and `photos` counts, and `eliteYear` for a Yelp Elite member.
|
|
272
|
+
|
|
273
|
+
A review the author later rewrote also carries `previousReviews`, holding the earlier version with its own text, rating and date. That is the field to read when the question is whether a rating moved, because the current review alone cannot answer it.
|
|
274
|
+
|
|
275
|
+
```json
|
|
276
|
+
{
|
|
277
|
+
"position": 1,
|
|
278
|
+
"id": "7zLIm3c2v2hRBVmgaKkR7w",
|
|
279
|
+
"link": "https://www.yelp.com/biz/desnudo-coffee-austin?hrid=7zLIm3c2v2hRBVmgaKkR7w",
|
|
280
|
+
"user": {
|
|
281
|
+
"name": "Karson S.",
|
|
282
|
+
"userId": "3LxSs_dQ37-LBRz07EDbyg",
|
|
283
|
+
"address": "Austin, TX",
|
|
284
|
+
"reviews": 374,
|
|
285
|
+
"friends": 61,
|
|
286
|
+
"photos": 875,
|
|
287
|
+
"eliteYear": "26"
|
|
288
|
+
},
|
|
289
|
+
"comment": { "text": "Coming back to Desnudo to update my old review...", "language": "en" },
|
|
290
|
+
"date": "2026-08-20T17:33:47-05:00",
|
|
291
|
+
"rating": 5,
|
|
292
|
+
"photos": [{ "link": "https://s3-media0.fl.yelpcdn.com/bphoto/YbjFKmRf7j0ejQQSaqtqVw/o.jpg", "caption": "Matcha latte", "width": 1126, "height": 2000 }],
|
|
293
|
+
"reactions": [{ "type": "HELPFUL", "label": "Helpful", "count": 1 }],
|
|
294
|
+
"previousReviews": [{ "id": "0WNI2IG7K1_Dg9zdXm03SA", "rating": 4, "comment": { "text": "..." } }]
|
|
295
|
+
}
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
## Errors and failure paths
|
|
299
|
+
|
|
300
|
+
Plan for these rather than assuming a happy path.
|
|
301
|
+
|
|
302
|
+
**A search with no matches returns a successful result with an empty `organicResults` array**, not an error. `requestMetadata.status` is still `ok`. Test the array length before iterating.
|
|
303
|
+
|
|
304
|
+
**`snippet` is marked-up text, not clean text.** Yelp wraps the matched words in `[[HIGHLIGHT]]` and `[[ENDHIGHLIGHT]]`, and those markers arrive verbatim. Strip them before you index, embed or display the snippet.
|
|
305
|
+
|
|
306
|
+
**Category URLs arrive HTML-escaped.** The `url` inside a `categories` entry contains `&` rather than a bare ampersand, because that is how it sits in the page. Unescape it before following the link.
|
|
307
|
+
|
|
308
|
+
**`rating` and `query` do not combine on the reviews tool.** Yelp ignores the star filter while a free-text query is running, so a filtered search comes back with reviews of every rating. Filter the result yourself when you need both.
|
|
309
|
+
|
|
310
|
+
**`start` and `nextPageToken` are two different ways to page, and they do not mix.** Pass one or the other. The token carries both the offset and the page size, so resending it alone continues the feed, while `start` needs `num` to stay put across calls.
|
|
311
|
+
|
|
312
|
+
**The not-recommended feed is a different feed with different limits.** Setting `notRecommended` returns reviews Yelp filtered out of the main list, and those come ten at a time rather than 49, with no photos, videos or reactions attached.
|
|
313
|
+
|
|
314
|
+
**A business can be unclaimed, and an unclaimed page is thin.** `isClaimed` false usually means no website, no hours and no amenities, because nobody filled them in. Read the flag before you treat a missing field as a scraping failure.
|
|
315
|
+
|
|
316
|
+
Results that carry data also carry a `requestMetadata.id` worth quoting in support.
|
|
317
|
+
|
|
318
|
+
## Pricing, free tier and limits
|
|
319
|
+
|
|
320
|
+
Each Yelp tool costs **10 credits per successful call**. Response size does not change the price, so a 49-review page and a 5-review page cost the same, which makes the largest page the cheapest way to read a feed.
|
|
321
|
+
|
|
322
|
+
The free tier is **1,000 credits every month with no card**, which is 100 Yelp calls at the base rate. It renews with the billing cycle, so a low-volume agent runs on the free tier indefinitely.
|
|
323
|
+
|
|
324
|
+
Paid plans start at **$49 a month** for 200,000 credits, which is 20,000 calls. The unit price falls with volume, from **$2.45 per 1,000 calls** on the entry plan to **$1.00** on Business, **$0.84** on Growth and **$0.74** on the largest [high-volume plans](https://hasdata.com/prices?utm_source=github&utm_medium=syndication&utm_campaign=yelp-mcp).
|
|
325
|
+
|
|
326
|
+
Your plan also sets concurrency. The free tier allows 1 request at a time, Startup 15, Business 30, Growth 50, and the high-volume plans run from 200 to 1,500. Handle the overflow case defensively in anything unattended, because an agent that fans out across a list of businesses will reach the ceiling before you do.
|
|
327
|
+
|
|
328
|
+
A request that comes back non-200 is not billed. A successful call that finds nothing is still a call.
|
|
329
|
+
|
|
330
|
+
## Tool selection
|
|
331
|
+
|
|
332
|
+
Start from what the prompt gives you. A keyword and a place go to the search tool, a Yelp ID or alias goes straight to the place tool, and a question about what customers said goes to the reviews tool. Spending a search call to reach an ID you already have is the most common waste.
|
|
333
|
+
|
|
334
|
+
Then pick by what the question is about. The place tool answers questions about the business itself, its hours, amenities, price tier and headline rating. The reviews tool answers questions about its customers, and it is the only one that returns review text, authors and the rating distribution. The `reviewHighlights` block on the place tool is a sample Yelp curates, not a substitute for the feed.
|
|
335
|
+
|
|
336
|
+
Read the feed with the largest page. `num` defaults to its maximum of 49 already, so leave it alone unless you are deliberately sampling.
|
|
337
|
+
|
|
338
|
+
## How it compares
|
|
339
|
+
|
|
340
|
+
Yelp's own Fusion API is the official route to this data, and it is a different instrument.
|
|
341
|
+
|
|
342
|
+
| | Yelp Fusion API | This server |
|
|
343
|
+
| :--- | :--- | :--- |
|
|
344
|
+
| Eligibility | An approved developer app | An API key |
|
|
345
|
+
| Review text | Up to three per business, truncated | The full feed, full text, paged |
|
|
346
|
+
| Review authors | Name and photo | Name, location, lifetime counts, Elite year |
|
|
347
|
+
| Rating distribution | Not returned | `reviewCountsByRating` on every call |
|
|
348
|
+
| Filtered reviews | Not returned | The not-recommended feed |
|
|
349
|
+
| Edit history | Not returned | `previousReviews` when a review was rewritten |
|
|
350
|
+
| Amenities and hours | A limited attribute set | The amenities block as the page shows it |
|
|
351
|
+
|
|
352
|
+
The row that decides it is review text. Fusion returns three excerpts per business, which answers a display question on a storefront and cannot answer an analysis question about sentiment, complaints or how a rating moved. When three excerpts and an official contract are what you need, Fusion is the better fit.
|
|
353
|
+
|
|
354
|
+
## FAQ
|
|
355
|
+
|
|
356
|
+
### Is there an official Yelp MCP server?
|
|
357
|
+
|
|
358
|
+
Yelp does not publish one. This one is maintained by HasData and reads public Yelp pages.
|
|
359
|
+
|
|
360
|
+
### What is a Yelp MCP server?
|
|
361
|
+
|
|
362
|
+
An MCP server exposes tools an AI client can call. This one turns Yelp search results, business pages and review feeds into JSON an agent can reason over, without a browser or a scraping library in your stack.
|
|
363
|
+
|
|
364
|
+
### Do I need a Yelp account or a Fusion key?
|
|
365
|
+
|
|
366
|
+
No. The only credential is your HasData key.
|
|
367
|
+
|
|
368
|
+
### Which Yelp sites are covered?
|
|
369
|
+
|
|
370
|
+
All 41 domains the API accepts, from `www.yelp.com` through the European, Asian and Latin American sites. Several countries have more than one, split by language, such as `fr.yelp.ca` next to `www.yelp.ca`. Pass `domain` to switch.
|
|
371
|
+
|
|
372
|
+
### Can I get every review of a business?
|
|
373
|
+
|
|
374
|
+
Yes, by paging. The feed returns 49 at a time, and `pagination.hasNextPage` tells you when to stop. Reading a business with 347 reviews takes eight calls.
|
|
375
|
+
|
|
376
|
+
### What is the difference between recommended and not-recommended reviews?
|
|
377
|
+
|
|
378
|
+
Yelp runs software that hides some reviews from the main feed. The default response is the recommended feed, the one a visitor sees. Setting `notRecommended` returns the hidden one instead, which is smaller, paged ten at a time, and stripped of photos and reactions.
|
|
379
|
+
|
|
380
|
+
### Why did my rating filter return every rating?
|
|
381
|
+
|
|
382
|
+
Because a `query` was set at the same time. Yelp drops the star filter when it runs a text search, so the two cannot be combined server-side.
|
|
383
|
+
|
|
384
|
+
### Can I use this together with other HasData APIs?
|
|
385
|
+
|
|
386
|
+
Yes. One key covers everything, and one endpoint serves them all through the `apis` parameter. Point a client at `?apis=yelp,google_maps` to get both tool sets in one connection, or at [`mcp.hasdata.com/api/mcp`](https://docs.hasdata.com/mcp-server?utm_source=github&utm_medium=syndication&utm_campaign=yelp-mcp) for the full catalogue.
|
|
387
|
+
|
|
388
|
+
### Is HasData affiliated with Yelp?
|
|
389
|
+
|
|
390
|
+
No. HasData is an independent service and is not affiliated with, endorsed by, or sponsored by Yelp. Yelp is a trademark of its respective owner. The tools work with publicly available data only, and you are responsible for using the results in line with Yelp's terms and the law that applies to you.
|
|
391
|
+
|
|
392
|
+
### Compliance and personal data
|
|
393
|
+
|
|
394
|
+
The review tools return personal data. A review carries the author's display name, profile photo, stated location, user ID and a link to their profile, and reviewers are private individuals rather than businesses. That puts the response in scope of the GDPR and the CCPA in a way a business listing is not. Decide what you actually need before you store it, keep it no longer than the purpose requires, and check your own obligations. Aggregate analysis rarely needs the author fields at all.
|
|
395
|
+
|
|
396
|
+
## HasData links
|
|
397
|
+
|
|
398
|
+
- [Yelp Scraper API](https://hasdata.com/apis/yelp-api?utm_source=github&utm_medium=syndication&utm_campaign=yelp-mcp), the REST endpoints behind these tools
|
|
399
|
+
- [API documentation](https://docs.hasdata.com/apis/yelp/search?utm_source=github&utm_medium=syndication&utm_campaign=yelp-mcp)
|
|
400
|
+
- [MCP server documentation](https://docs.hasdata.com/mcp-server?utm_source=github&utm_medium=syndication&utm_campaign=yelp-mcp)
|
|
401
|
+
- [Pricing](https://hasdata.com/prices?utm_source=github&utm_medium=syndication&utm_campaign=yelp-mcp)
|
|
402
|
+
- [Dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=yelp-mcp)
|
|
403
|
+
|
|
404
|
+
Other HasData MCP servers: [Google Search](https://github.com/HasData/google-search-mcp), [Google Maps](https://github.com/HasData/google-maps-mcp), [Google Trends](https://github.com/HasData/google-trends-mcp), [Google Flights](https://github.com/HasData/google-flights-mcp), [DuckDuckGo](https://github.com/HasData/duckduckgo-mcp), [YouTube](https://github.com/HasData/youtube-mcp), [TikTok](https://github.com/HasData/tiktok-mcp), [Instagram](https://github.com/HasData/instagram-mcp), [Amazon](https://github.com/HasData/amazon-mcp), [Zillow](https://github.com/HasData/zillow-mcp), [Airbnb](https://github.com/HasData/airbnb-mcp), [Booking.com](https://github.com/HasData/booking-mcp), [Indeed](https://github.com/HasData/indeed-mcp).
|
|
405
|
+
|
|
406
|
+
## Development
|
|
407
|
+
|
|
408
|
+
The launcher is a thin stdio bridge to the remote server, so there is nothing to build.
|
|
409
|
+
|
|
410
|
+
```bash
|
|
411
|
+
npm install
|
|
412
|
+
HASDATA_API_KEY=your_key_here npm test
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
The tests in `test/` assert the tool contract, the part that can break without a commit here. They check that `?apis=yelp` returns the expected tool count, that no name changed, that every tool still declares its required parameters and carries a description, and that the key in use is actually accepted. That last check calls a tool for real and costs 10 credits, which is the price of a canary that can fail for the right reason.
|
|
416
|
+
|
|
417
|
+
The contract suite also runs weekly on a schedule, because the upstream tool list can change without anyone touching this repository.
|
|
418
|
+
|
|
419
|
+
## Contributing
|
|
420
|
+
|
|
421
|
+
A tool table, a response sample or a documented behaviour that does not match reality is worth an issue. There is a template for exactly that. Pull requests are welcome for the same, and for anything in the launcher.
|
|
422
|
+
|
|
423
|
+
## License
|
|
424
|
+
|
|
425
|
+
MIT, see [LICENSE](LICENSE).
|
package/index.mjs
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Thin launcher: connects an MCP client to HasData's hosted Yelp MCP server
|
|
3
|
+
// (streamable HTTP) through the mcp-remote stdio bridge. The server runs remotely.
|
|
4
|
+
// This package only proxies, so nothing here scrapes anything.
|
|
5
|
+
import { spawn } from 'node:child_process';
|
|
6
|
+
import { createRequire } from 'node:module';
|
|
7
|
+
import { dirname, join } from 'node:path';
|
|
8
|
+
|
|
9
|
+
const URL = 'https://mcp.hasdata.com/api/mcp?apis=yelp';
|
|
10
|
+
const key = process.env.HASDATA_API_KEY;
|
|
11
|
+
if (!key) {
|
|
12
|
+
process.stderr.write('HASDATA_API_KEY is not set. Create a free key at https://app.hasdata.com and set HASDATA_API_KEY.\n');
|
|
13
|
+
process.exit(1);
|
|
14
|
+
}
|
|
15
|
+
// Resolve mcp-remote's CLI from its own package.json bin, so a future layout change
|
|
16
|
+
// or an exports map does not break a hardcoded deep path.
|
|
17
|
+
const require = createRequire(import.meta.url);
|
|
18
|
+
const pkg = require('mcp-remote/package.json');
|
|
19
|
+
const proxy = join(dirname(require.resolve('mcp-remote/package.json')), pkg.bin['mcp-remote']);
|
|
20
|
+
const child = spawn(process.execPath, [proxy, URL, '--header', `x-api-key:${key}`], { stdio: 'inherit' });
|
|
21
|
+
child.on('exit', (code, signal) => {
|
|
22
|
+
if (signal) process.kill(process.pid, signal);
|
|
23
|
+
else process.exit(code ?? 0);
|
|
24
|
+
});
|
package/package.json
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@hasdata/yelp-mcp",
|
|
3
|
+
"mcpName": "com.hasdata/yelp",
|
|
4
|
+
"version": "1.0.0",
|
|
5
|
+
"description": "MCP server for Yelp through HasData's hosted API: business search, place details and the full review feed. No Yelp Fusion key, no waitlist. 1,000 free credits every month.",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"bin": {
|
|
8
|
+
"hasdata-yelp-mcp": "index.mjs"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"index.mjs",
|
|
12
|
+
"README.md",
|
|
13
|
+
"LICENSE"
|
|
14
|
+
],
|
|
15
|
+
"scripts": {
|
|
16
|
+
"test": "node --test"
|
|
17
|
+
},
|
|
18
|
+
"dependencies": {
|
|
19
|
+
"mcp-remote": "^0.1.43"
|
|
20
|
+
},
|
|
21
|
+
"engines": {
|
|
22
|
+
"node": ">=18"
|
|
23
|
+
},
|
|
24
|
+
"license": "MIT",
|
|
25
|
+
"repository": {
|
|
26
|
+
"type": "git",
|
|
27
|
+
"url": "https://github.com/HasData/yelp-mcp.git"
|
|
28
|
+
},
|
|
29
|
+
"homepage": "https://hasdata.com/apis/yelp-api",
|
|
30
|
+
"keywords": [
|
|
31
|
+
"mcp",
|
|
32
|
+
"yelp",
|
|
33
|
+
"yelp-mcp",
|
|
34
|
+
"reviews",
|
|
35
|
+
"local-business",
|
|
36
|
+
"local-seo",
|
|
37
|
+
"model-context-protocol",
|
|
38
|
+
"hasdata",
|
|
39
|
+
"scraper"
|
|
40
|
+
]
|
|
41
|
+
}
|