Purpose
yelp-mcp is a hosted Model Context Protocol (MCP) server that lets Claude, Cursor, Windsurf, and other MCP clients read Yelp's public information as structured JSON. It provides three read-only tools: search businesses by keyword and location, read the full details of a single business, and page through a business's complete review stream. No Yelp Fusion key is required, and there is no need to self-host any container.
It reads public Yelp pages visible to logged-out visitors, covering 41 regional domains.
Main capabilities
The three tools consume 10 credits per successful call, and all accept a domain parameter for switching country/region (41 possible values, from www.yelp.com to European, Asian, and Latin American sites, including language variants such as fr.yelp.ca and zh.yelp.com.hk).
Search (hasdata_yelp_search_getSearchResults): returns one page of businesses for a keyword in a specified location. The response includes searchInformation(the echoed keyword, location, totalResults),ads a paid ads array,organicResults an organic results array, and pagination information (currentPage, perPage, totalPages, nextPageUrl, otherPagesUrls). The two result arrays have different structures: organic results have position and streetAddress, while ads do not have these two fields but additionally have phone and a highlights badge array. If the two arrays are merged without distinguishing their source, paid placements will be mistaken for rankings.
Business details (hasdata_yelp_place_getPlaceDetails): returns a placeResult object containing name, url, address, neighborhoods, country, phone, website, price, categories, rating, reviews, isClaimed, isClaimable, as well as operationHours (weekly opening hours plus today), a features array, a menu object (including popularDishes), a faqs array, a reviewHighlights array, an images array, and businessMap (a static map image URL). features is the amenities section, and each item has a title and an isActive flag; false means Yelp explicitly states that the amenity does not exist, rather than being unknown; when filtering, discarding false entries and discarding missing entries do not mean the same thing.
Review stream (hasdata_yelp_reviews_getPlaceReviews): returns the complete review text for a single business, with support for sorting, filtering, and pagination. The response includes searchInformation (business name, alias, URL, totalResults, rating, a reviewCountsByRating array, and a reviewCountsByLanguage breakdown), a pagination object, and a reviews array. Each review includes position, id, link, a user object, a comment object (text and detected language), date, rating, and optional photos, videos, reactions. The user object reports name, userId, address, lifetime review count, friend count, photo count, and eliteYear for Yelp Elite members. Reviews later rewritten by the author also carry previousReviews, which stores the old version's text, rating, and date—when the question involves whether the rating changed, this field is key, because looking only at the current review cannot answer it.
The server also provides a prompt (a preset workflow), as well as 2 resources, each corresponding to a parameter with a fixed value, with the URI format hasdata://yelp/<parameter>. Reading resources does not consume credits and does not require an API key.
How to use
An MCP client and a HasData API key are required (created for free in the dashboard, no credit card required; the free tier, calculated at 10 credits per call, supports about 100 calls per month). This is a remote server, and the simplest path is the URL plus the x-api-key header, with no need to run a container. Clients that only support stdio can access it through a lightweight launcher, which has been published as the npm package @hasdata/yelp-mcp and the PyPI package hasdata-yelp-mcp.
The server URL is the same for all clients:https://mcp.hasdata.com/mcp?apis=yelp.
Clients that support OAuth can add this URL as a connector and log in directly, without putting a secret in a configuration file. In Settings → Connectors → Add custom connector, paste the above URL and log in.
For the configuration file approach, Claude Desktop only loads local (stdio) servers, so reach the remote server through the stdio launcher.@hasdata/yelp-mcp The package is that launcher and reads the secret from an environment variable. Add it to claude_desktop_config.json. If you use Python instead of Node, you can switch to the PyPI package, run by uvx without manual installation.
Cursor: put the configuration in ~/.cursor/mcp.json(all projects) or .cursor/mcp.json(a single project).
Windsurf: the configuration file is ~/.codeium/windsurf/mcp_config.json, the field name is serverUrl rather than url.
VS Code: use the workspace's .vscode/mcp.json.
When to use
Typical prompt examples:
- Find coffee roasters in Austin, TX, and rank them by rating and review count.
- Get the business hours, phone number, and website for the Yelp business desnudo-coffee-austin.
- Read all one-star and two-star reviews for this business and group the complaints by topic.
- Which popular dishes does Yelp list for this store, and what do reviewers say about them?
- Compare the rating distributions of three competitors in the same neighborhood.
- Show reviews that Yelp does not recommend, and compare the differences with recommended reviews.
If a prompt names a business directly rather than a Yelp ID, two calls are needed: one search to resolve the ID, and one detail or review read. The search tool returns both placeId and placeAlias, and either can be used as the placeId parameter for the place tool.
Limitations and considerations
- When a search has no match, it returns a successful result but organicResults is an empty array, and requestMetadata.status is still ok. Check the array length before iterating.
- snippet is text with markers; Yelp wraps matching terms in [[HIGHLIGHT]] and [[ENDHIGHLIGHT]], which need to be stripped before indexing, embedding, or display.
- Category URLs are HTML-escaped; the url in categories entries contains
&rather than a bare &, it must be unescaped first. - rating and query cannot be combined on the reviews tool: Yelp ignores the star rating filter when running a full-text query, so if you need both you must filter the results yourself.
- start and nextPageToken are two different pagination methods and cannot be mixed. The token carries both the offset and the page size, so simply resending it continues; start requires num to remain constant across multiple calls.
- notRecommended returns reviews that Yelp has filtered out of the main list, 10 at a time (rather than 49), and without photos, videos, or reactions.
- A business may be unclaimed, and unclaimed pages have sparse information: isClaimed being false usually means there is no website, business hours, or amenities, because no one has filled them in. Missing fields should be distinguished from this.
- Responses that carry data also carry requestMetadata.id, making them easy to reference when supported.
Billing and Concurrency
Each successful call costs 10 credits, and response size does not affect the price, so a 49-review page costs the same as a 5-review page; when reading a review stream, choosing the largest page is the most cost-effective.
The free tier gives 1,000 credits per month with no credit card required, i.e. 100 calls at the base rate, and resets with the billing cycle, so low-traffic agents can use the free tier long term.
Paid plans start at $59/month for 200,000 credits (i.e. 20,000 calls), with the unit price decreasing as volume grows, from $2.95 per thousand in the entry plan down to $1.19 for Basic and $0.83 across the Growth tiers. See the pricing page for the latest numbers. The plan also determines concurrency: 1 request at a time on the free tier, 5 for Startup, 15 for Basic, and 50 to 500 across the Growth tiers. In unattended scenarios, a 429 should be handled with backoff and retry, because agents expanding across multiple businesses will hit the limit first. Non-200 responses are not billed, but successful calls with no results are still billed.
Comparison with Other Solutions
Yelp's official Fusion API is the official way to get this data, but it is different in nature. What decides the trade-off is the review text: Fusion returns three excerpts per business, which is fine for storefront display questions but cannot answer analytical questions about sentiment, complaints, or rating changes. If you need three excerpts and an official contract, Fusion is more suitable.
Yelp has not released an official MCP server; this server is maintained by HasData and only reads public Yelp pages.
Compliance and Personal Data
The reviews tool returns personal data: reviews carry the author's display name, avatar, stated location, user ID, and profile link, and reviewers are mostly individuals rather than businesses, which makes the responses more sensitive under GDPR and CCPA than business listings. Before storing, you should decide what you actually need, retain it no longer than necessary for the purpose, and verify your own obligations. Aggregated analysis usually does not need author fields at all.
HasData is not affiliated with, endorsed by, or sponsored by Yelp, and Yelp is a trademark of its respective owners. The tools use only public data, and users must ensure that their use complies with Yelp's terms and applicable law.
Other
The launcher is a lightweight stdio bridge to the remote server, with no build required.test/ tests the tool contract, checking that ?apis=yelp returns the expected number of tools, that the names have not changed, that each tool still declares required parameters and includes descriptions, and that the keys used are actually accepted; the last item makes real tool calls and consumes 10 credits. The contract suite also runs on a weekly schedule, because the upstream tool list may change even when this repository has not. Licensed under the MIT License, see LICENSE for details.
