Yelp MCP

🚀 MCP Server for Yelp Fusion AI

Yelp Fusion AI brings conversational intelligence to your applications. It allows users to ask natural - language questions and get real - time, contextually relevant answers, powered by Yelp’s latest business data and reviews.

🚀 Quick Start

This server is designed to work with Yelp Fusion AI, enabling seamless interaction with Yelp's business data through natural - language queries. To start using it, you'll need to set up the environment and configure the server as described in the following sections.

✨ Features

Fusion AI Capabilities

• Next generation search & discovery: Search using natural language, discover, and connect with contextually relevant businesses. For example, you can ask "Find the best tacos in the Bay Area".
• Multi - turn conversations: Support back - and - forth interactions and refine queries with follow - up questions. Such as "Which of the options have open air seating?".
• Direct business queries: Ask targeted questions about businesses without a prior search. For instance, "Does Ricky’s Taco allow pets?".
• Conversational restaurant reservations: Explore availability and book a table at restaurants via natural - language interactions. Note that this is available on request only. To enable reservations, contact us. For example, you can say "Reserve a table for 4 tomorrow at 8PM at Ricky’s".

Tools

This server exposes one primary tool:

• yelp_agent: Designed for agent - to - agent communication. It handles natural - language requests about local businesses, providing both natural - language responses and structured business data. It supports follow - up questions using a chat_id. Capabilities include business search, detailed questions, comparisons, itinerary planning, etc., leveraging Yelp's dataset. Key Arguments:
  • natural_language_query (str): Your query (e.g., "find the best tacos in the Bay Area").
  • search_latitude (float or null): Latitude for location - specific searches.
  • search_longitude (float or null): Longitude for location - specific searches.
  • chat_id (str or null): ID for continuing a previous conversation.

📦 Installation

Prerequisites

You need either a container manager (like Docker or Podman) or the following installed locally:

• Python: Version 3.10 or higher (as specified in pyproject.toml).
• uv: The Python package manager. Find installation instructions at https://docs.astral.sh/uv/.

You also need an API key for Yelp Fusion AI. You can get a key by creating an app here to start your free trial. If you need more time to evaluate, email us at fusion@yelp.com to extend your trial.

Find more details and comprehensive documentation about Yelp Fusion AI here.

Setup and Installation Steps

1. Clone the repository:

git clone <repository_url>
cd yelp-mcp

2. Install dependencies: This command will create a virtual environment (if one doesn't exist), install all necessary dependencies as defined in pyproject.toml and uv.lock, and install the project into the uv environment.

make install

Building the Docker Image (Optional)

If you prefer to run the server in a container, you can build a Docker image:

docker build -t mcp-yelp-agent .

This will create an image named mcp-yelp-agent:latest.

💻 Usage Examples

Running the Server

This repository is designed to be run as a Model Context Protocol server. You need an MCP client (like compatible versions of Claude, Cursor, or VS Code with MCP support) to interact with it.

Method 1: Running without Docker

Ensure you have completed the "Setup and Installation" steps, especially installing the project so the mcp-yelp-agent script is available.

Server Configuration

The server supports multiple transport protocols and can be configured with command - line arguments. While stdio is the primary transport for most MCP clients, other options are available for different use cases.

• --transport: Choose the communication protocol.
  • stdio (default): Standard input/output, ideal for local tools.
  • streamable-http: Streamable HTTP.
  • sse: Server - Sent Events.
• --host: The host address to bind to (e.g., 127.0.0.1 or 0.0.0.0). Default is 127.0.0.1.
• --port: The port to listen on. Default is 8000.

Configure your MCP client with the following JSON settings to run the server with the default stdio transport:

{
  "mcpServers": {
    "yelp_agent": {
      "command": "uv",
      "args": [
        "--directory",
        "<PATH_TO_YOUR_CLONED_PROJECT_DIRECTORY>",
        "run",
        "mcp-yelp-agent"
      ],
      "env": {
        "YELP_API_KEY": "<YOUR_YELP_FUSION_API_KEY>"
      }
    }
  }
}

Notes:

• Replace <PATH_TO_YOUR_CLONED_PROJECT_DIRECTORY> with the absolute path to where you cloned this project.
• Replace <YOUR_YELP_FUSION_API_KEY> with your actual Yelp Fusion API key.
• If your MCP client has trouble invoking uv directly, you might need to provide the full path to the uv binary. You can find this by running which uv in your terminal.

Method 2: Running with Docker

Ensure you have built the Docker image as described in "Building the Docker Image". Configure your MCP client with the following JSON settings:

{
  "mcpServers": {
    "yelp_agent": {
      "command": "docker",
      "args": [
        "run",
        "-i",          // Interactive mode
        "--rm",        // Automatically remove the container when it exits
        "--init",      // Run an init process as PID 1 in the container
        "-e", "YELP_API_KEY=<YOUR_YELP_FUSION_API_KEY>",
        "mcp-yelp-agent:latest" // The image name built earlier
      ]
    }
  }
}

Notes:

• Replace <YOUR_YELP_FUSION_API_KEY> with your actual Yelp Fusion API key.
• If your MCP client has trouble invoking docker from the system PATH, you might need to provide the full path to its binary (e.g., run which docker).