yelp-mcp-sdk

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.

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-sdk .
docker buildx build -t yelp-mcp-sdk .
docker run --env-file .env yelp-mcp-sdk

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

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} — Full Yelp business profile as application/json. Declared via list_resource_templates; fetched via read_resource.

Project structure

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

Running tests

uv run pytest -v

Comparison with yelp-mcp-min (FastMCP)

Aspect	yelp-mcp-min (FastMCP)	yelp-mcp-sdk (official SDK)
Tool registration	@mcp.tool() decorator	list_tools + call_tool dispatcher
Input schema	Auto-generated from func sig	model.model_json_schema() explicit
Output type	Return Pydantic model directly	list[TextContent] with JSON string
Resources	@mcp.resource("uri://...") decorator	list_resource_templates + read_resource pair
Dependency inject	None (captured via closure)	lifespan context → request_context
Transport	mcp.run()	asyncio.run() + stdio_server()
Server LOC	~350	~450