Yelp MCP server for AI agents

Yelp Fusion AI MCP Server enables conversational intelligence in your applications, allowing users to ask natural language questions about businesses and receive relevant answers powered by Yelp's business data and reviews. This server implements the Model Context Protocol (MCP) to provide seamless integration with compatible clients.

Prerequisites

Before installing the MCP server, you need:

A container manager like Docker or Podman, OR
Python 3.10 or higher
The uv package manager (installation instructions at https://docs.astral.sh/uv/)

You'll also need a Yelp Fusion AI API key, which you can get by creating an app here. This will start your free trial. For extended evaluation time, email [email protected].

More details about Yelp Fusion AI are available in the comprehensive documentation.

Setup and Installation

Clone the repository:

git clone <repository_url>
cd yelp-mcp

Install dependencies:

make install

This creates a virtual environment, installs all necessary dependencies from pyproject.toml and uv.lock, and installs the project into the uv environment.

Building the Docker Image (Optional)

If you prefer running the server in a container:

docker build -t mcp-yelp-agent .

This creates an image named mcp-yelp-agent:latest.

Running the Server

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

Server Configuration Options

The server supports multiple transport protocols with these configuration options:

--transport: Communication protocol
- stdio (default): Standard input/output
- streamable-http: Streamable HTTP
- sse: Server-Sent Events
--host: Host address (default: 127.0.0.1)
--port: Port to listen on (default: 8000)

Method 1: Running without Docker

Configure your MCP client with these JSON settings to run 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 the cloned project
Replace <YOUR_YELP_FUSION_API_KEY> with your actual Yelp Fusion API key
If your MCP client has trouble invoking uv directly, provide the full path to the uv binary (find it by running which uv in your terminal)

Method 2: Running with Docker

After building the Docker image, configure your MCP client with these JSON settings:

{
  "mcpServers": {
    "yelp_agent": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "YELP_API_KEY=<YOUR_YELP_FUSION_API_KEY>",
        "mcp-yelp-agent:latest"
      ]
    }
  }
}

Notes:

Replace <YOUR_YELP_FUSION_API_KEY> with your actual Yelp Fusion API key
If your MCP client has trouble invoking docker, provide the full path to its binary

Using the Yelp Agent Tool

The server exposes one primary tool:

yelp_agent

This tool handles natural language requests about local businesses, providing both natural language responses and structured business data. It supports:

Business search and discovery
Multi-turn conversations with follow-up questions
Direct business queries
Conversational restaurant reservations (available on request)

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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>"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "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>"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "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>"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect