Yelp Min

Minimal MCP server for the Yelp Fusion API v3, built with FastMCP 3.

Prerequisites

• Python 3.11+
• uv 0.11+
• Docker (optional)
• A Yelp Fusion API key — https://www.yelp.com/developers/v3/manage_app

Installation

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

Running

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

Environment variables

Variable	Required	Default	Description
YELP_API_KEY	Yes	—	Yelp Fusion API bearer token
YELP_BASE_URL	No	https://api.yelp.com/v3	API base URL
HTTP_TIMEOUT	No	10.0	Request timeout in seconds
HTTP_MAX_RETRIES	No	3	Max retry attempts on 429/5xx
HTTP_RETRY_WAIT_MIN	No	1.0	Min back-off wait in seconds
HTTP_RETRY_WAIT_MAX	No	10.0	Max back-off wait in seconds
LOG_LEVEL	No	INFO	structlog level
JSON_LOGS	No	false	Emit JSON log lines (for Datadog etc)

Tools

Tool	Yelp endpoint	Description
search_businesses	GET /v3/businesses/search	Full-text + geo search with pagination
find_business_by_phone	GET /v3/businesses/search/phone	Look up a business by E.164 phone number
match_business	GET /v3/businesses/matches	Match structured name+address to Yelp listing
get_business	GET /v3/businesses/{id}	Full business profile by Yelp ID or alias
get_business_reviews	GET /v3/businesses/{id}/reviews	Customer reviews with pagination

Resource

yelp://business/{id} — Returns the same payload as get_business as an MCP resource (application/json). MCP clients that support resources can embed or subscribe to this URI directly.

Project structure

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

Running tests

uv run pytest -v