Yelp MCP Server

Pesquisa de negócios do Yelp, detalhes de lugares e o feed completo de avaliações, como JSON estruturado.

Documentação

Servidor MCP do Yelp

Um servidor de Model Context Protocol (MCP) hospedado que oferece ao Claude, Cursor, Windsurf e qualquer outro cliente MCP três ferramentas somente leitura do Yelp. Pesquise empresas por palavra-chave e localização, leia uma empresa por completo e navegue pelo feed completo de avaliações, tudo como JSON estruturado, sem chave do Yelp Fusion e sem nada para hospedar.

Ele lê páginas públicas do Yelp que um visitante não autenticado pode ver, em qualquer um dos 41 domínios regionais.

1.000 créditos grátis todo mês, sem cartão de crédito, o que equivale a 100 chamadas ao Yelp na taxa de 10 créditos.

https://mcp.hasdata.com/api/mcp?apis=yelp

O que você precisa

Um cliente MCP e uma chave de API do HasData do painel de controle, gratuita para criar sem cartão, e o plano gratuito cobre cerca de 100 chamadas por mês na taxa de 10 créditos. Este é um servidor remoto, então o caminho mais simples é uma URL e um cabeçalho x-api-key, sem contêiner para executar. Um cliente que só fala stdio o acessa por meio de um lançador leve, publicado como @hasdata/yelp-mcp no npm e hasdata-yelp-mcp no PyPI, mostrado abaixo.

Início rápido

A URL do servidor é a mesma para todos os clientes. Nós o testamos na prática no Claude Code e no Claude Desktop. Os outros blocos seguem o formato documentado de cada cliente para um servidor remoto.

Campo	Valor
URL	`https://mcp.hasdata.com/api/mcp?apis=yelp`
Transporte	HTTP, com streaming
Cabeçalho de autenticação	`x-api-key: HASDATA_API_KEY`

Clientes com suporte a OAuth podem adicionar a mesma URL como um conector e entrar sem colocar uma chave em um arquivo de configuração.

Claude Code

claude mcp add --transport http yelp "https://mcp.hasdata.com/api/mcp?apis=yelp" \
  --header "x-api-key: HASDATA_API_KEY"

Claude Desktop

Configurações, depois Conectores, depois Adicionar conector personalizado, depois cole https://mcp.hasdata.com/api/mcp?apis=yelp e entre.

Para o caminho do arquivo de configuração, o Claude Desktop carrega apenas servidores locais (stdio), então ele acessa um servidor remoto por meio de um lançador stdio. O pacote @hasdata/yelp-mcp é esse lançador, e ele lê a chave do ambiente. Adicione isto ao claude_desktop_config.json:

{
  "mcpServers": {
    "yelp": {
      "command": "npx",
      "args": ["-y", "@hasdata/yelp-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

Para Python em vez de Node, troque o lançador pelo pacote do PyPI, que o uvx executa sem instalação manual:

{
  "mcpServers": {
    "yelp": {
      "command": "uvx",
      "args": ["hasdata-yelp-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

Cursor

~/.cursor/mcp.json para todos os projetos, ou .cursor/mcp.json para um único:

{
  "mcpServers": {
    "yelp": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=yelp",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json. O Windsurf chama o campo de serverUrl, não de url:

{
  "mcpServers": {
    "yelp": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=yelp",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

VS Code

.vscode/mcp.json no espaço de trabalho:

{
  "servers": {
    "yelp": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=yelp",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

Exemplos de prompts

Cada um destes usa uma ferramenta, ou duas em sequência quando a segunda precisa de um identificador que a primeira retorna.

Encontre torrefações de café em Austin, TX e classifique-as por avaliação em relação ao número de avaliações.
Puxe os horários, o telefone e o site da empresa do Yelp desnudo-coffee-austin.
Leia todas as avaliações de uma e duas estrelas desta empresa e agrupe as reclamações por tema.
Quais pratos o Yelp lista como populares para este lugar, e o que os avaliadores dizem sobre eles?
Compare a distribuição de avaliações destes três concorrentes no mesmo bairro.
Mostre-me as avaliações que o Yelp não recomenda para esta empresa e como elas diferem das recomendadas.

Um prompt que nomeia uma empresa em vez de um ID do Yelp faz duas chamadas: uma busca para resolver o ID e uma consulta de lugar ou de avaliações para lê-lo. A ferramenta de busca retorna tanto placeId quanto placeAlias, e qualquer um dos dois funciona como o argumento placeId para a ferramenta de lugar.

Ferramentas

Três ferramentas, 10 créditos por chamada bem-sucedida. Toda ferramenta aceita domain para trocar de país, um dos 41 valores, de www.yelp.com até os sites europeus, asiáticos e latino-americanos, incluindo as variantes específicas de idioma, como fr.yelp.ca e zh.yelp.com.hk.

Obter resultados de busca do Yelp

hasdata_yelp_search_getSearchResults

Uma página de empresas para uma palavra-chave em um lugar.

Parâmetro	Tipo	Obrigatório	Observações
`keyword`	string	sim	O que buscar, como `coffee`
`location`	string	sim	Onde buscar, como `Austin, TX`
`l`	string		Caixa delimitadora de mapa em vez de um raio, como `g:lon1,lat1,lon2,lat2`
`domain`	string		Site do Yelp, padrão é `www.yelp.com`
`start`	number		Deslocamento do resultado, em passos de 10

Retorna searchInformation com o keyword ecoado, location e totalResults, um array ads de posições pagas, um array organicResults e pagination com currentPage, perPage, totalPages, nextPageUrl e otherPagesUrls.

Os dois arrays de resultados não têm o mesmo formato. Um resultado orgânico carrega position e streetAddress, enquanto um anúncio não carrega nenhum dos dois e adiciona phone e um array highlights dos selos que o Yelp mostra aos anunciantes. Mesclar os arrays sem verificar de qual empresa cada uma veio transforma posição paga em classificação.

{
  "position": 2,
  "placeId": "oiJ7QuhhpsEpe9zFTZF0bA",
  "placeAlias": "desnudo-coffee-austin",
  "url": "https://www.yelp.com/biz/desnudo-coffee-austin",
  "title": "Desnudo Coffee",
  "streetAddress": "2505 Webberville Rd, Austin",
  "price": "$$",
  "categories": [{ "title": "Coffee Roasteries", "url": "https://www.yelp.com/search?find_desc=Coffee+Roasteries&amp;find_loc=Austin%2C+TX" }],
  "snippet": "My favorite coffee shop to go to ever! Everyone must go. [[HIGHLIGHT]]Great coffee[[ENDHIGHLIGHT]], great vibes,great customer...",
  "rating": 4.7,
  "reviews": 347,
  "thumbnail": "https://s3-media0.fl.yelpcdn.com/bphoto/0nE_IcbRiyxrw3kk2z6owg/ls.jpg",
  "allImagesUrl": "https://www.yelp.com/biz_photos/oiJ7QuhhpsEpe9zFTZF0bA"
}

Obter detalhes do lugar no Yelp

hasdata_yelp_place_getPlaceDetails

Uma empresa por completo.

Parâmetro	Tipo	Obrigatório	Observações
`placeId`	string	sim	Um ID do Yelp como `oiJ7QuhhpsEpe9zFTZF0bA`, ou um alias como `desnudo-coffee-austin`
`domain`	string		Site do Yelp, padrão é `www.yelp.com`

Retorna um objeto placeResult com name, url, address, neighborhoods, country, phone, website, price, categories, rating, reviews, isClaimed e isClaimable, um objeto operationHours com uma semana de hours mais today, um array features, um objeto menu com popularDishes, um array faqs de perguntas que leitores do Yelp fizeram e responderam, um array reviewHighlights das frases que o Yelp fixa no topo da página, um array images e businessMap, uma URL de imagem de mapa estático.

features é o bloco de comodidades, e cada entrada carrega um title e um sinalizador isActive, então uma entrada falsa significa que o Yelp afirma que a comodidade está ausente, e não que é desconhecida. Essa diferença importa ao filtrar, porque descartar as entradas falsas e descartar as ausentes não são a mesma consulta.

{
  "name": "Desnudo Coffee",
  "url": "https://www.yelp.com/biz/desnudo-coffee-austin",
  "address": "2505 Webberville Rd Austin, TX 78702",
  "neighborhoods": "East Austin",
  "country": "US",
  "phone": "(424) 400-1857",
  "website": "http://www.desnudocoffee.com",
  "price": "$$",
  "categories": ["Coffee Roasteries"],
  "rating": 4.7,
  "reviews": 347,
  "isClaimed": true,
  "isClaimable": false,
  "operationHours": { "hours": [{ "day": "Mon", "hours": ["7:00 AM - 2:00 PM"] }] },
  "features": [
    { "title": "Offers delivery", "isActive": true },
    { "title": "ADA-compliant restroom", "isActive": false }
  ],
  "menu": {
    "section": "Popular Drinks",
    "popularDishes": [{ "name": "Brown Sugar Miso Latte", "rating": 4.7, "reviews": 113, "photos": 71 }]
  }
}

Obter avaliações do lugar no Yelp

hasdata_yelp_reviews_getPlaceReviews

O feed de avaliações de uma empresa, em texto completo, com ordenação, filtragem e paginação.

Parâmetro	Tipo	Obrigatório	Observações
`placeId`	string	sim	O ID do Yelp da empresa
`domain`	string		Site do Yelp, padrão é `www.yelp.com`
`sortBy`	string		`relevanceDesc` (padrão), `dateDesc`, `dateAsc`, `ratingDesc`, `ratingAsc` ou `elitesDesc`
`rating`	string		Manter apenas estas classificações por estrelas, como `5` ou `1,2`
`query`	string		Busca por texto livre dentro das avaliações
`languageCode`	string		Idioma das avaliações em duas letras, padrão é `en`
`notRecommended`	boolean		Retornar o feed que o Yelp filtra em vez do recomendado
`start`	number		Deslocamento, em passos de `num`
`num`	number		Tamanho da página, no máximo 49, e 49 por padrão
`nextPageToken`	string		Cursor copiado literalmente da resposta anterior

Retorna searchInformation com o nome da empresa, alias, URL, totalResults, rating, um array reviewCountsByRating e um detalhamento reviewCountsByLanguage, um objeto pagination e um array reviews.

Cada avaliação carrega position, id, link, um objeto user, um objeto comment com text e seu language detectado, date, rating e, quando o avaliador os anexou, photos, videos e reactions. O objeto user informa name, userId, address, contagens de reviews vitalício, friends e photos, e eliteYear para um membro do Yelp Elite.

Uma avaliação que o autor reescreveu depois também carrega previousReviews, com a versão anterior, incluindo seu próprio texto, classificação e data. Esse é o campo a ler quando a pergunta é se uma classificação mudou, porque a avaliação atual sozinha não consegue responder.

{
  "position": 1,
  "id": "7zLIm3c2v2hRBVmgaKkR7w",
  "link": "https://www.yelp.com/biz/desnudo-coffee-austin?hrid=7zLIm3c2v2hRBVmgaKkR7w",
  "user": {
    "name": "Karson S.",
    "userId": "3LxSs_dQ37-LBRz07EDbyg",
    "address": "Austin, TX",
    "reviews": 374,
    "friends": 61,
    "photos": 875,
    "eliteYear": "26"
  },
  "comment": { "text": "Coming back to Desnudo to update my old review...", "language": "en" },
  "date": "2026-08-20T17:33:47-05:00",
  "rating": 5,
  "photos": [{ "link": "https://s3-media0.fl.yelpcdn.com/bphoto/YbjFKmRf7j0ejQQSaqtqVw/o.jpg", "caption": "Matcha latte", "width": 1126, "height": 2000 }],
  "reactions": [{ "type": "HELPFUL", "label": "Helpful", "count": 1 }],
  "previousReviews": [{ "id": "0WNI2IG7K1_Dg9zdXm03SA", "rating": 4, "comment": { "text": "..." } }]
}

Erros e caminhos de falha

Planeje estes cenários em vez de assumir um caminho feliz.

Uma busca sem correspondências retorna um resultado bem-sucedido com um array organicResults vazio, não um erro. requestMetadata.status ainda é ok. Teste o tamanho do array antes de iterar.

snippet é texto com marcação, não texto limpo. O Yelp envolve as palavras correspondentes em [[HIGHLIGHT]] e [[ENDHIGHLIGHT]], e esses marcadores chegam literalmente. Remova-os antes de indexar, incorporar ou exibir o trecho.

URLs de categoria chegam com escape de HTML. O url dentro de uma entrada categories contém & em vez de um e comercial simples, porque é assim que está na página. Remova o escape antes de seguir o link.

rating e query não se combinam na ferramenta de avaliações. O Yelp ignora o filtro de estrelas enquanto uma consulta de texto livre está em execução, então uma busca filtrada volta com avaliações de todas as classificações. Filtre o resultado você mesmo quando precisar de ambos.

start e nextPageToken são duas maneiras diferentes de paginar, e elas não se misturam. Passe um ou outro. O token carrega tanto o deslocamento quanto o tamanho da página, então reenviá-lo sozinho continua o feed, enquanto start precisa que num permaneça o mesmo entre chamadas.

O feed não recomendado é um feed diferente, com limites diferentes. Definir notRecommended retorna avaliações que o Yelp filtrou da lista principal, e elas vêm dez por vez em vez de 49, sem fotos, vídeos ou reações anexadas.

Uma empresa pode não ser reivindicada, e uma página não reivindicada é enxuta. isClaimed falso geralmente significa sem site, sem horários e sem comodidades, porque ninguém os preencheu. Leia o sinalizador antes de tratar um campo ausente como falha de raspagem.

Resultados que carregam dados também carregam um requestMetadata.id que vale citar no suporte.

Preços, plano gratuito e limites

Cada ferramenta do Yelp custa 10 créditos por chamada bem-sucedida. O tamanho da resposta não muda o preço, então uma página com 49 avaliações e uma com 5 avaliações custam o mesmo, o que torna a maior página a maneira mais barata de ler um feed.

O plano gratuito é 1.000 créditos todo mês, sem cartão, o que equivale a 100 chamadas ao Yelp na taxa base. Ele renova com o ciclo de cobrança, então um agente de baixo volume roda no plano gratuito indefinidamente. Planos pagos começam em US$ 49 por mês para 200.000 créditos, o que equivale a 20.000 chamadas. O preço unitário cai com o volume, de US$ 2,45 por 1.000 chamadas no plano inicial para US$ 1,00 no Business, US$ 0,84 no Growth e US$ 0,74 nos maiores planos de alto volume.

Seu plano também define a concorrência. O nível gratuito permite 1 solicitação por vez, Startup 15, Business 30, Growth 50, e os planos de alto volume variam de 200 a 1.500. Faça nova tentativa no 429 com backoff em qualquer processo não supervisionado, porque um agente que se espalha por uma lista de empresas atingirá o teto antes de você.

Uma solicitação que retorna com status diferente de 200 não é cobrada. Uma chamada bem-sucedida que não encontra nada ainda é uma chamada.

Seleção de ferramentas

Comece pelo que o prompt fornece. Uma palavra-chave e um local vão para a ferramenta de busca, um ID ou alias do Yelp vai direto para a ferramenta de local, e uma pergunta sobre o que os clientes disseram vai para a ferramenta de avaliações. Gastar uma chamada de busca para chegar a um ID que você já tem é o desperdício mais comum.

Depois, escolha pelo que a pergunta aborda. A ferramenta de local responde perguntas sobre o negócio em si, seus horários, comodidades, faixa de preço e classificação principal. A ferramenta de avaliações responde perguntas sobre seus clientes, e é a única que retorna texto de avaliação, autores e a distribuição de classificações. O bloco reviewHighlights na ferramenta de local é uma amostra que o Yelp seleciona, não um substituto para o feed.

Leia o feed com a maior página. num já usa o máximo de 49 por padrão, então deixe como está, a menos que você esteja deliberadamente amostrando.

Como se compara

A própria Fusion API do Yelp é a rota oficial para esses dados, e é um instrumento diferente.

	Yelp Fusion API	Este servidor
Elegibilidade	Um aplicativo de desenvolvedor aprovado	Uma chave de API
Texto de avaliação	Até três por empresa, truncado	O feed completo, texto completo, paginado
Autores de avaliação	Nome e foto	Nome, localização, contagens vitalícias, ano Elite
Distribuição de classificações	Não retornada	`reviewCountsByRating` em cada chamada
Avaliações filtradas	Não retornadas	O feed não recomendado
Histórico de edições	Não retornado	`previousReviews` quando uma avaliação foi reescrita
Comodidades e horários	Um conjunto limitado de atributos	O bloco de comodidades como a página mostra

A linha que decide é o texto de avaliação. A Fusion retorna três trechos por empresa, o que responde a uma pergunta de exibição em uma vitrine e não pode responder a uma pergunta de análise sobre sentimento, reclamações ou como uma classificação mudou. Quando três trechos e um contrato oficial são o que você precisa, a Fusion é a melhor opção.

FAQ

Existe um servidor MCP oficial do Yelp?

O Yelp não publica um. Este é mantido pela HasData e lê páginas públicas do Yelp.

O que é um servidor MCP do Yelp?

Um servidor MCP expõe ferramentas que um cliente de IA pode chamar. Este transforma resultados de busca do Yelp, páginas de empresas e feeds de avaliações em JSON que um agente pode raciocinar, sem um navegador ou uma biblioteca de scraping em sua stack.

Preciso de uma conta Yelp ou de uma chave Fusion?

Não. A única credencial é sua chave HasData.

Quais sites do Yelp são cobertos?

Todos os 41 domínios que a API aceita, de www.yelp.com até os sites europeus, asiáticos e latino-americanos. Vários países têm mais de um, divididos por idioma, como fr.yelp.ca ao lado de www.yelp.ca. Passe domain para alternar.

Posso obter todas as avaliações de uma empresa?

Sim, paginando. O feed retorna 49 por vez, e pagination.hasNextPage informa quando parar. Ler uma empresa com 347 avaliações leva oito chamadas.

Qual é a diferença entre avaliações recomendadas e não recomendadas?

O Yelp executa software que oculta algumas avaliações do feed principal. A resposta padrão é o feed recomendado, o que um visitante vê. Definir notRecommended retorna o oculto em vez disso, que é menor, paginado dez por vez, e sem fotos e reações.

Por que meu filtro de classificação retornou todas as classificações?

Porque um query foi definido ao mesmo tempo. O Yelp descarta o filtro de estrelas quando executa uma busca por texto, então os dois não podem ser combinados no lado do servidor.

Posso usar isso junto com outras APIs da HasData?

Sim. Uma chave cobre tudo, e um endpoint atende a todos através do parâmetro apis. Aponte um cliente para ?apis=yelp,google_maps para obter ambos os conjuntos de ferramentas em uma conexão, ou para mcp.hasdata.com/api/mcp para o catálogo completo.

A HasData é afiliada ao Yelp?

Não. A HasData é um serviço independente e não é afiliada, endossada ou patrocinada pelo Yelp. Yelp é uma marca registrada de seu respectivo proprietário. As ferramentas trabalham apenas com dados publicamente disponíveis, e você é responsável por usar os resultados de acordo com os termos do Yelp e a lei que se aplica a você.

Conformidade e dados pessoais

As ferramentas de avaliação retornam dados pessoais. Uma avaliação carrega o nome de exibição do autor, foto de perfil, localização declarada, ID de usuário e um link para seu perfil, e os avaliadores são indivíduos privados, não empresas. Isso coloca a resposta no escopo do GDPR e do CCPA de uma forma que uma listagem de empresa não está. Decida o que você precisa antes de armazenar, mantenha apenas pelo tempo que o propósito exigir, e verifique suas próprias obrigações. Análise agregada raramente precisa dos campos de autor.

Links da HasData

Yelp Scraper API, os endpoints REST por trás dessas ferramentas
Documentação da API
Documentação do servidor MCP
Preços
Painel

Outros servidores MCP da HasData: Google Search, Google Maps, Google Trends, Google Flights, DuckDuckGo, YouTube, TikTok, Instagram, Amazon, Zillow, Airbnb, Booking.com, Indeed.

Desenvolvimento

O lançador é uma ponte stdio fina para o servidor remoto, então não há nada para compilar.

npm install
HASDATA_API_KEY=your_key_here npm test

Os testes em test/ verificam o contrato da ferramenta, a parte que pode quebrar sem um commit aqui. Eles verificam que ?apis=yelp retorna a contagem esperada de ferramentas, que nenhum nome mudou, que cada ferramenta ainda declara seus parâmetros obrigatórios e carrega uma descrição, e que a chave em uso é realmente aceita. Esse último check chama uma ferramenta de verdade e custa 10 créditos, que é o preço de um canário que pode falhar pelo motivo certo.

A suíte de contrato também roda semanalmente em um cronograma, porque a lista de ferramentas upstream pode mudar sem que ninguém toque neste repositório.

Contribuindo

Uma tabela de ferramentas, uma amostra de resposta ou um comportamento documentado que não corresponde à realidade vale uma issue. Há um template exatamente para isso. Pull requests são bem-vindos para o mesmo, e para qualquer coisa no lançador.

Licença

MIT, veja LICENSE.