iflow-mcp_yelp-mcp 0.1.0
An example MCP server exposing tools to interact with Yelp
Requires Python: >=3.10

# **MCP Server for Yelp Fusion AI**

[Yelp Fusion AI](https://business.yelp.com/data/products/fusion-ai/) brings conversational intelligence to your applications, enabling users to ask natural language questions and receive real-time, contextually relevant answers powered by Yelp’s latest business data and reviews.

### Fusion AI Capabilities

* **Next generation search & discovery** – Search with natural language, discover, and connect with contextually relevant businesses. *("Find the best tacos in the Bay Area")*
* **Multi-turn conversations** – Support back-and-forth interactions and refine queries with follow-up questions. *("Which of the options have open air seating?")*
* **Direct business queries** – Ask targeted questions about businesses without needing to perform a prior search. *("Does Ricky’s Taco allow pets?")*
* **Conversational restaurant reservations** – Explore availability and book a table at restaurants through natural language interactions. (Please note that this is available on **request only**. To enable reservations, please [contact us](https://business.yelp.com/data/products/fusion-ai/?utm_source=GitHub&utm_medium=Readme#form).) *("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. This tool 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, and more, 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.

## **Prerequisites**

You either need a container manager (like [Docker](https://docker.com) or [Podman](https://podman.io)) or the following installed locally:

* **Python:** Version 3.10 or higher (as specified in pyproject.toml).
* **uv**: The Python package manager. You can find installation instructions at [https://docs.astral.sh/uv/](https://docs.astral.sh/uv/).

You will also need an API key for Yelp Fusion AI. You can get a key by [creating an app here](https://www.yelp.com/developers/v3/manage_app?utm_source=GitHub&utm_medium=Readme), which will start your free trial. If you need more time to evaluate, email us at [fusion@yelp.com](mailto:fusion@yelp.com) to extend your trial.

Find more details and [comprehensive documentation about Yelp Fusion AI here.](https://docs.developer.yelp.com/reference/v2_ai_chat?utm_source=GitHub&utm_medium=Readme)

## **Setup and Installation**

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.

## **Running the Server**

This repository is designed to be run as a [Model Context Protocol server](https://modelcontextprotocol.io/docs/concepts/architecture). You will 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`.

### **Method 1: Running without Docker**

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

```json
{
  "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:

```json
{
  "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).