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 |