Provides tools for searching businesses by text and location, looking up businesses by phone number, matching structured name and address to Yelp listings, retrieving full business profiles, and fetching reviews, all via the Yelp Fusion API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@yelp-mcp-sdk search for coffee shops in Seattle"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Yelp Fusion MCP server built on the official MCP Python SDK.
Functionally identical to yelp-mcp-min (FastMCP), but uses the low-level
Server class directly — no framework abstractions.
Python 3.11+
uv 0.11+
Docker (optional)
A Yelp Fusion API key — https://www.yelp.com/developers/v3/manage_app
Related MCP server: Yelp Fusion MCP Server
uv sync
cp .env.example .env
# Edit .env and set YELP_API_KEY# stdio transport (for use with Claude Desktop or an MCP client)
uv run python -m server.main
# Docker
docker build -t yelp-mcp-sdk .
docker buildx build -t yelp-mcp-sdk .
docker run --env-file .env yelp-mcp-sdkVariable | Required | Default | Description |
| Yes | — | Yelp Fusion API bearer token |
| No |
| API base URL |
| No |
| Request timeout in seconds |
| No |
| Max retry attempts on 429/5xx |
| No |
| Min back-off wait in seconds |
| No |
| Max back-off wait in seconds |
| No |
| structlog level |
| No |
| Emit JSON log lines |
Tool | Yelp endpoint | Description |
|
| Full-text + geo search with pagination |
|
| Look up a business by E.164 phone number |
|
| Match structured name+address to Yelp listing |
|
| Full business profile by Yelp ID or alias |
|
| Customer reviews with pagination |
yelp://business/{id} — Full Yelp business profile as application/json.
Declared via list_resource_templates; fetched via read_resource.
yelp-mcp-sdk/
server/
main.py # Server("yelp-mcp", lifespan=...) + stdio run
core/
config.py # pydantic-settings
logging.py # structlog → stderr
client.py # async httpx + tenacity retry
models.py # Pydantic output models
handlers/
params.py # Pydantic input models (also generate inputSchema)
tools.py # list_tools() + call_tool() dispatcher
resources.py # list_resource_templates() + read_resource()
tests/
conftest.py
test_client.py
test_models.py
test_handlers.py
Dockerfile
pyproject.toml
.env.exampleuv run pytest -vAspect | yelp-mcp-min (FastMCP) | yelp-mcp-sdk (official SDK) |
Tool registration |
|
|
Input schema | Auto-generated from func sig |
|
Output type | Return Pydantic model directly |
|
Resources |
|
|
Dependency inject | None (captured via closure) |
|
Transport |
|
|
Server LOC | ~350 | ~450 |
Look up Yelp businesses that match a phone number. Use when you have a phone number and need to identify the business. Phone must be in E.164 format (+14155551234). Returns up to a handful of candidates; empty list means not found.
| Name | Required | Description | Default |
|---|---|---|---|
| phone | Yes | E.164 phone number including country code, e.g. '+14155551234'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent. Description adds behavioral details: results limited to 'a handful of candidates', empty list means not found. This clarifies nondeterminism and false negatives beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. First sentence defines purpose and usage context. Second sentence covers format and output expectations. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 1 parameter and no output schema, description covers all essential aspects: action, usage scenario, input format, and result interpretation. No gaps for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100% and schema already describes phone format thoroughly. Description merely reaffirms format without adding new meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'look up' and resource 'Yelp businesses' with specific filter 'phone number'. Differentiates from siblings like 'search_businesses' (generic) or 'get_business' (by ID) by focusing on phone lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States when to use: 'when you have a phone number and need to identify the business'. Provides format requirement (E.164) and explains return behavior (few candidates, empty if not found). No explicit when-not, but context implies it's the dedicated phone lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full Yelp profile for a specific business by its ID or alias. Use when you already have a Yelp business ID and need complete details: hours, all photos, full address, price tier, categories, and URL. Raises an error if the business ID does not exist on Yelp.
| Name | Required | Description | Default |
|---|---|---|---|
| business_id | Yes | Yelp business ID or alias, e.g. 'tartine-bakery-san-francisco'. Obtain from search_businesses, find_business_by_phone, or match_business. | |
| locale | No | BCP 47 locale, e.g. 'en_US', 'fr_FR'. Defaults to en_US. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it raises an error if the business ID does not exist on Yelp, which is valuable behavioral detail. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. First sentence states purpose and scope. Second sentence adds usage guidance and error behavior. Perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description lists key returned fields (hours, photos, address, price tier, categories, URL), which is sufficient for a read-only data fetch. Could mention that it returns a single object, but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters have descriptions). The description adds value by specifying the source for business_id ('Obtain from search_businesses, find_business_by_phone, or match_business') and noting the default locale ('en_US').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Fetch the full Yelp profile') and the resource ('a specific business by its ID or alias'). It distinguishes from siblings like search_businesses (which searches by query) and find_business_by_phone (by phone number).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when you already have a Yelp business ID and need complete details.' This provides clear context. However, it does not explicitly state when not to use it or mention alternatives like search_businesses if the ID is not known.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve user reviews for a specific Yelp business. Use when the user wants to read customer opinions: ratings, comments, and reviewer info. Returns up to 50 reviews per call. Use offset to paginate; total field shows how many reviews exist.
| Name | Required | Description | Default |
|---|---|---|---|
| business_id | Yes | Yelp business ID or alias. Obtain from search_businesses, find_business_by_phone, or match_business. | |
| locale | No | BCP 47 locale to filter by language, e.g. 'en_US'. | |
| sort_by | No | Sort: 'yelp_sort' (default), 'newest', 'oldest', 'highest_rated', 'lowest_rated'. | |
| limit | No | Reviews per page (1–50, default 20). | |
| offset | No | Zero-based offset for pagination. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds behavioral context beyond annotations: returns up to 50 reviews, use offset for pagination, total field shows total count. Annotations already indicate readOnly and idempotent, so the description adds useful operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with front-loaded purpose, then usage guidance, then behavioral trait. No wasted words; each sentence adds distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description covers return fields (ratings, comments, reviewer info) and pagination. Mentions total field. Missing default sort or result structure, but overall adequate for a read-only tool with rich schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds minimal extra meaning: mentions pagination via offset and limit, and that total field exists. Does not elaborate on sort_by or locale beyond what schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves user reviews for a specific Yelp business, with details on ratings, comments, and reviewer info. Distinguished from sibling tools like search_businesses or get_business which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when the user wants to read customer opinions' and describes return content. Provides pagination limits (up to 50) and offset usage. Does not explicitly mention when not to use, but the sibling context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Match a business by name and address to its canonical Yelp listing. Use when you have structured address data and need to verify or enrich it with Yelp data such as ID, rating, hours, and URL. name + address1 + city + state + country are required. Adding zip_code and phone significantly improves match precision.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Business name, e.g. 'Tartine Bakery'. | |
| address1 | Yes | Street address, e.g. '600 Guerrero St'. | |
| city | Yes | City name, e.g. 'San Francisco'. | |
| state | Yes | ISO 3166-2 state/region code, e.g. 'CA'. | |
| country | Yes | ISO 3166-1 alpha-2 country code, e.g. 'US'. | |
| zip_code | No | Postal code. Improves match accuracy. | |
| phone | No | E.164 phone number. Improves match accuracy. | |
| match_threshold | No | Match strictness: 'NONE', 'DEFAULT', or 'STRICT'. | DEFAULT |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool is read-only and idempotent. The description adds behavioral context by listing required fields and noting that optional fields improve match precision, plus the match_threshold parameter. It does not contradict annotations, but it does not explicitly describe behavior on no match or multiple matches.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: first declares purpose, second provides usage context, third adds parameter guidance. Every sentence is essential and front-loaded, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately hints at return fields (ID, rating, hours, URL) and includes match_threshold options. It could improve by clarifying behavior when no match is found, but it remains sufficiently informative for an agent to decide to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so each parameter is documented. The description adds value by grouping required fields and explaining that zip_code and phone improve match precision, which goes beyond the schema's individual descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Match a business by name and address to its canonical Yelp listing.' It specifies the purpose of verification/enrichment and distinguishes itself from sibling tools like search_businesses or get_business by focusing on structured address matching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use the tool: 'Use when you have structured address data and need to verify or enrich it with Yelp data.' It also notes required and optional fields. However, it does not explicitly state when not to use it or mention alternative tools, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Yelp for businesses matching a term, location, or both. Use when the user wants to discover restaurants, services, or shops. Supports free-text search, geo coordinates, category filters, price tiers, open-now filtering, and pagination via limit/offset. Supply at least one of: location, or both latitude + longitude.
| Name | Required | Description | Default |
|---|---|---|---|
| term | No | Search term, e.g. 'tacos', 'coffee', 'plumbers'. Omit to browse by location only. | |
| location | No | Address, neighbourhood, city, or ZIP code. Required unless latitude + longitude are provided. | |
| latitude | No | Decimal latitude. Pair with longitude. | |
| longitude | No | Decimal longitude. Pair with latitude. | |
| radius | No | Search radius in metres (max 40 000 ≈ 25 miles). | |
| categories | No | Comma-separated Yelp category aliases, e.g. 'restaurants,bars'. | |
| price | No | Comma-separated price tiers: '1'=$, '2'=$$, '3'=$$$, '4'=$$$$. Example: '1,2'. | |
| open_now | No | When True, only return businesses currently open. | |
| sort_by | No | Sort order: 'best_match' (default), 'rating', 'review_count', or 'distance'. | |
| limit | No | Results per page (1–50, default 20). | |
| offset | No | Zero-based offset. Use with limit to paginate: page 2 = offset 20 when limit=20. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=false, openWorldHint=true, so the read-only nature is clear. The description adds no extra behavioral details (e.g., rate limits, result variability, pagination quirks) beyond what the schema and annotations convey, but does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is four sentences, front-loads the main action, and every sentence is informative. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 11-parameter search tool with full schema coverage and annotations, the description adequately summarizes the tool's capabilities and constraints. It misses stating the return format, but no output schema exists, so some inference is needed. However, the overall context is sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description only summarizes available filter types (free-text, geo, categories, price, open-now, pagination) without adding new semantic meaning beyond the detailed schema descriptions for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Search Yelp for businesses matching a term, location, or both' with a clear verb+resource. Mentions discovering restaurants, services, shops. Does not explicitly distinguish from siblings like find_business_by_phone or get_business, but the sibling names are self-explanatory and this tool's purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context: 'Use when the user wants to discover restaurants, services, or shops.' Also notes requirement for location or lat/lng and lists supported features. However, it does not mention when not to use this tool or provide alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0find_business_by_phoneget_businessget_business_reviewsmatch_businesssearch_businessesScored across 5 tools
Each tool has a clearly distinct purpose: phone lookup, get full business details, get reviews, match by name/address, and general search. No overlapping functionality, making selection unambiguous.
All tools follow a consistent snake_case verb_noun pattern (e.g., find_business_by_phone, get_business, search_businesses), with clear modifiers where needed. No mixing of conventions.
Five tools is well-scoped for a Yelp API wrapper: covering search, matching, detailed lookup, reviews, and phone lookup. It's neither overly sparse nor bloated.
The tool set covers the core Yelp use cases—discovery, matching, detailed info, and reviews. There are no obvious gaps for read-only access, as mutations are not part of Yelp's public API.
Yelp MCP — wraps the Yelp Fusion API (api.yelp.com/v3)
Yelp business search, place details and the full review feed, as structured JSON.
4 Yelp endpoints. Pay per call in USDC via x402.
Live Google Maps business search, review, and photo data for AI agents over MCP.
