Skip to main content
Glama
yelp-mcp-min

yelp-mcp-min

by miqui

yelp-mcp-min

Servidor MCP minimalista para la API v3 de Yelp Fusion, construido con FastMCP 3.

Requisitos previos

Related MCP server: yelp-mcp-sdk

Instalación

uv sync
cp .env.example .env
# Edit .env and set YELP_API_KEY

Ejecució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

YELP_API_KEY

Sí

—

Token de portador de la API de Yelp Fusion

YELP_BASE_URL

No

https://api.yelp.com/v3

URL base de la API

HTTP_TIMEOUT

No

10.0

Tiempo de espera de solicitud en segundos

HTTP_MAX_RETRIES

No

3

Intentos máximos de reintento en 429/5xx

HTTP_RETRY_WAIT_MIN

No

1.0

Espera mínima de retroceso en segundos

HTTP_RETRY_WAIT_MAX

No

10.0

Espera máxima de retroceso en segundos

LOG_LEVEL

No

INFO

Nivel de structlog

JSON_LOGS

No

false

Emitir líneas de registro JSON (para Datadog, etc.)

Herramientas

Herramienta

Endpoint de Yelp

Descripción

search_businesses

GET /v3/businesses/search

Búsqueda de texto completo + geo con paginación

find_business_by_phone

GET /v3/businesses/search/phone

Buscar un negocio por número de teléfono E.164

match_business

GET /v3/businesses/matches

Coincidir nombre+dirección estructurados con el listado de Yelp

get_business

GET /v3/businesses/{id}

Perfil completo del negocio por ID o alias de Yelp

get_business_reviews

GET /v3/businesses/{id}/reviews

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.example

Ejecución de pruebas

uv run pytest -v

Available Tools

5 tools
find_business_by_phoneA
Read-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_businessA
Read-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_reviewsA
Read-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_businessA
Read-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_businessesA
Read-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

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct use case: phone lookup, ID-based details, reviews, name+address matching, and keyword/location search. No functional overlap exists.

    Naming Consistency5/5

    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.

    Tool Count5/5

    Five tools is appropriate for a Yelp information server, covering the essential operations without being too sparse or overly granular.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      1
      29
      Apache 2.0
    • F
      license
      A
      quality
      D
      maintenance
      Provides Yelp Fusion API access through MCP tools and resources for searching businesses, getting reviews, and more.
      5
      -
    • A
      license
      C
      quality
      C
      maintenance
      FastMCP server that exposes the YNAB API for budget management, enabling interaction with YNAB data through MCP tools.
      44
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for Yelp integration, enabling AI agents to search for local businesses, read reviews, view photos, check hours, find deals, and discover trending spots.
      12
      49 npm
      MIT