yelp-mcp-min
yelp-mcp-min
Servidor MCP minimalista para la API v3 de Yelp Fusion, construido con FastMCP 3.
Requisitos previos
Python 3.11+
uv 0.11+
Docker (opcional)
Una clave de API de Yelp Fusion — https://www.yelp.com/developers/v3/manage_app
Related MCP server: yelp-mcp-sdk
Instalación
uv sync
cp .env.example .env
# Edit .env and set YELP_API_KEYEjecución
# stdio transport (for use with Claude Desktop or an MCP client)
uv run python -m server.main
# Docker
docker build -t yelp-mcp-min .
docker run --env-file .env yelp-mcp-min
docker buildx build -t yelp-mcp-min .Variables de entorno
Variable | Requerido | Predeterminado | Descripción |
| Sí | — | Token de portador de la API de Yelp Fusion |
| No |
| URL base de la API |
| No |
| Tiempo de espera de solicitud en segundos |
| No |
| Intentos máximos de reintento en 429/5xx |
| No |
| Espera mínima de retroceso en segundos |
| No |
| Espera máxima de retroceso en segundos |
| No |
| Nivel de structlog |
| No |
| Emitir líneas de registro JSON (para Datadog, etc.) |
Herramientas
Herramienta | Endpoint de Yelp | Descripción |
|
| Búsqueda de texto completo + geo con paginación |
|
| Buscar un negocio por número de teléfono E.164 |
|
| Coincidir nombre+dirección estructurados con el listado de Yelp |
|
| Perfil completo del negocio por ID o alias de Yelp |
|
| Reseñas de clientes con paginación |
Recurso
yelp://business/{id} — Devuelve la misma carga útil que get_business como un recurso MCP (application/json). Los clientes MCP que admiten recursos pueden incrustar o suscribirse a este URI directamente.
Estructura del proyecto
yelp-mcp-min/
server/
main.py # FastMCP instance + wiring
core/
config.py # pydantic-settings (YELP_API_KEY, tunables)
logging.py # structlog setup (stderr only)
client.py # async httpx client, retry, error mapping
models.py # Pydantic output models
tools/
search.py # search_businesses
business.py # find_by_phone, match, get_business
reviews.py # get_business_reviews
resources/
business.py # yelp://business/{id}
tests/
conftest.py
test_client.py
test_tools.py
test_models.py
Dockerfile
pyproject.toml
.env.exampleEjecución de pruebas
uv run pytest -vAvailable Tools
5 toolsfind_business_by_phoneARead-onlyIdempotent
Look up Yelp businesses that match a phone number.
Use this when you have a phone number and need to identify which business it belongs to. Returns up to a handful of candidates ranked by relevance. An empty list means no Yelp listing was found for that number.
The phone must include the country code in E.164 format (+14155551234).
Inputs: params (required). Returns: result
get_businessARead-onlyIdempotent
Fetch the full Yelp profile for a specific business by its ID or alias.
Use this when you already have a Yelp business ID (from search results or a previous call) and need complete details: hours, all photos, full address, price tier, categories, and the Yelp URL.
Raises an error if the business ID does not exist on Yelp.
Inputs: params (required). Returns: Full business record returned by get_business and match_business.
get_business_reviewsARead-onlyIdempotent
Retrieve user reviews for a specific Yelp business.
Use this when the user wants to read what customers say about a business: sentiment, specific comments about food, service, or atmosphere. Returns up to 50 reviews per call with text excerpts, star ratings, and reviewer info.
The 'total' field in the response shows how many reviews exist in full; use 'offset' to paginate through them.
Raises an error if the business ID does not exist on Yelp.
Inputs: params (required). Returns: Wrapper returned by get_business_reviews.
match_businessARead-onlyIdempotent
Match a business by name and address to its canonical Yelp listing.
Use this when you have structured address data (from a CRM, spreadsheet, or user input) and need to verify or enrich it with Yelp data such as the Yelp ID, rating, hours, and URL.
Name + address1 + city + state + country are required. Adding zip_code and phone significantly improves match precision.
Returns ranked candidates; the first result is the best match. An empty list means no match was found at the chosen threshold.
Inputs: params (required). Returns: result
search_businessesARead-only
Search Yelp for businesses matching a term, location, or both.
Use this tool when the user wants to discover businesses — restaurants, services, shops, entertainment — in a given area. It supports free-text search, geo coordinates, category filters, price tiers, open-now filtering, and pagination.
Supply at least one of: location, or both latitude + longitude.
Returns a list of matching businesses with ratings, review counts, price tier, address, and a Yelp URL. The 'total' field indicates how many results exist in the full result set; use 'offset' to paginate.
Raises ValueError when neither location nor coordinates are provided.
Inputs: params (required). Returns: Wrapper returned by search_businesses.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct use case: phone lookup, ID-based details, reviews, name+address matching, and keyword/location search. No functional overlap exists.
All tool names follow the verb_noun pattern in snake_case, starting with 'get', 'find', 'match', or 'search' followed by 'business' or 'businesses'. Highly consistent.
Five tools is appropriate for a Yelp information server, covering the essential operations without being too sparse or overly granular.
The tool set covers the main read operations for Yelp business data: search, direct lookup by ID, phone, or name+address, and reviews. No critical gaps for typical usage.
Maintenance
Related MCP Connectors
Unofficial Yelp MCP — wraps the Yelp Fusion API (api.yelp.com/v3)
MCP server for the GovContractScout US government contracts API: search, NAICS, match scoring.
An MCP server that exposes functionalities to use Zomato's services.
Yelp business search, place details and the full review feed, as structured JSON.
Related MCP Servers
AlicenseAqualityCmaintenanceEnables conversational interactions with Yelp's business data through an MCP server, allowing natural language queries about local businesses, multi-turn conversations, and direct business inquiries powered by Yelp Fusion AI.129Apache 2.0- FlicenseAqualityDmaintenanceProvides Yelp Fusion API access through MCP tools and resources for searching businesses, getting reviews, and more.5-
- AlicenseCqualityCmaintenanceFastMCP server that exposes the YNAB API for budget management, enabling interaction with YNAB data through MCP tools.441MIT
- AlicenseAqualityDmaintenanceMCP server for Yelp integration, enabling AI agents to search for local businesses, read reviews, view photos, check hours, find deals, and discover trending spots.1249 npmMIT