Yellow Pages MCP Server

Servidor MCP Yellow Pages

Um servidor de Model Context Protocol (MCP) hospedado que oferece ao Claude, Cursor, Windsurf e qualquer outro cliente MCP duas ferramentas somente leitura do Yellow Pages. Pesquise empresas locais por palavra-chave e localização e, em seguida, leia um anúncio completo com telefone, horários, serviços e fotos, tudo como JSON estruturado, sem precisar hospedar nada.

Ele lê anúncios públicos do Yellow Pages que um visitante não autenticado pode ver, em yellowpages.com e yellowpages.ca.

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

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

Conteúdo

• O que você precisa
• Início rápido
• Exemplos de prompts
• Ferramentas
• Erros e caminhos de falha
• Preços, plano gratuito e limites
• Seleção de ferramentas
• Comparação
• FAQ
• Links HasData
• Desenvolvimento
• Contribuição
• Licença

O que você precisa

Um cliente MCP e uma chave de API HasData do painel, 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/yellowpages-mcp no npm e hasdata-yellowpages-mcp no PyPI, mostrado abaixo.

Início rápido

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

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

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

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

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

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

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

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

Exemplos de prompts

Cada um destes cai em uma ferramenta, ou em duas em sequência quando a segunda precisa da URL que a primeira retorna.

• Encontre encanadores em Austin, TX e classifique-os por avaliação em relação à contagem de avaliações.
• Liste todos os contratantes de HVAC neste CEP com telefone e horários.
• Quais dessas empresas estão em atividade há mais de 20 anos?
• Leia este anúncio do Yellow Pages e me diga quais marcas eles atendem.
• Puxe as páginas 2 e 3 de telhadistas em Austin e mescle-as em uma única lista.
• Ordene dentistas nesta cidade por avaliação média em vez de relevância.

Um prompt que nomeia um nicho e uma cidade vai para a ferramenta de busca. Ler serviços, marcas e formas de pagamento exige uma segunda chamada por empresa, então uma lista de prospecção quer a ferramenta de busca e uma passada de enriquecimento quer a ferramenta de local.

Ferramentas

Duas ferramentas, 10 créditos por chamada bem-sucedida.

Obter resultados de busca do Yellow Pages

hasdata_yellowpages_search_getSearchResults

Uma página de empresas para uma palavra-chave em um local, 30 por página.

Retorna searchInformation com a consulta repetida e totalResults, um array de organicResults, e pagination com currentPage, totalPages, perPage, nextPageUrl e otherPageUrls.

Quase todo campo em um resultado é opcional, porque o Yellow Pages mostra o que cada empresa pagou ou preencheu. Entre os 30 resultados da amostra, title, phone, url, categories, country e position chegaram em todos, address em 22, rating e reviews em 11, e contactUs em 5. Leia de forma defensiva em vez de assumir uma forma.

{
  "position": 2,
  "title": "Clarke Kent Plumbing",
  "url": "https://www.yellowpages.com/austin-tx/mip/clarke-kent-plumbing-10674347?lid=1002194068759",
  "phone": "(512) 766-0970",
  "address": "1408 W Ben White Blvd",
  "city": "Austin",
  "region": "TX",
  "zipcode": "78704",
  "country": "US",
  "website": "http://www.clarkekentplumbing.com",
  "directions": "https://www.yellowpages.com/listings/1002194068759/directions",
  "categories": ["Plumbers", "Plumbing-Drain & Sewer Cleaning"],
  "rating": 2.87,
  "reviews": 15,
  "workingHours": ["Mo-Fr 09:00-17:00"],
  "openState": "open now",
  "badges": ["40 Years in Business", "1 Year with Yellow Pages"]
}

Obter detalhes do local no Yellow Pages

hasdata_yellowpages_place_getPlaceDetails

Um anúncio completo, pela sua URL do Yellow Pages.

Retorna quatro blocos em vez de um único objeto plano.

overview repete o nome, localização, telefone, horários, selos e site, e adiciona paymentAccepted e um array de breadcrumbs mostrando onde o anúncio se encaixa na taxonomia do Yellow Pages. ratings contém a classificação por estrelas. details contém o texto longo que a empresa escreveu. images é um array de URLs de fotos.

O bloco details é onde está o valor de enriquecimento, e ele chega como texto unido por vírgulas em vez de arrays. generalInfo é a descrição da empresa, servicesProducts a lista de serviços, brands as marcas que eles vendem, paymentMethod os tipos de pagamento e categories a lista completa de categorias como uma única string.

{
  "overview": {
    "title": "ARS Rescue Rooter",
    "phone": "(833) 947-9225",
    "city": "Austin",
    "region": "TX",
    "zipcode": "78754",
    "workingHours": ["Mo-Su"],
    "openState": "Open 24 hours",
    "paymentAccepted": "visa, amex, master card",
    "badges": ["1 Year with Yellow Pages"],
    "breadcrumbs": ["TX", "Austin", "Building Contractors", "Plumbers"]
  },
  "ratings": { "rating": 3.5 },
  "details": {
    "generalInfo": "ARS/Rescue Rooter has a proven track record of providing reliable, long-lasting repair services...",
    "servicesProducts": "Air Conditioner Repair and Replacement, Air Duct Repair and Replacement, Air Filter Installation...",
    "brands": "Goodman, Mitsubishi, Bosch, Diakin, Bradford White, April Aire Indoor Air Quality",
    "paymentMethod": "visa, amex, master card"
  },
  "images": ["https://i4.ypcdn.com/blob/ce73451958465ab47dd7be41922973a98bc847af_640.jpg"]
}

Erros e caminhos de falha

Planeje para estes em vez de assumir um caminho feliz.

Para uma contagem de avaliações, leia o resultado da busca em vez do detalhe do local. Na ferramenta de busca, rating e reviews são o que parecem, como 2.87 e 15. Na ferramenta de local, ratings.reviews volta igual a ratings.rating em todos os anúncios que verificamos, então não carrega contagem. Pegue o número do resultado da busca e enriqueça a partir daí.

ratings pode estar ausente de uma resposta de local inteiramente. Um dos quatro anúncios que puxamos não tinha bloco algum em vez de um vazio.

Os campos details são strings unidas por vírgulas, e categories muda de tipo entre as ferramentas. Em um resultado de busca, categories é um array. Em details, é uma única string. Divida na vírgula se precisar de uma lista, e espere que algum nome de categoria estranho contenha uma.

website às vezes aponta de volta para o Yellow Pages. Vários anúncios carregam uma URL de rastreamento yellowpages.com no campo onde você esperaria o site da própria empresa. Verifique o host antes de segui-la ou armazená-la.

Anos em atividade é um selo, não um campo. badges mistura duas coisas diferentes: há quanto tempo a empresa opera, como "40 Years in Business", e há quanto tempo ela paga o Yellow Pages, como "11 Years with Yellow Pages". Leia o texto em vez do primeiro número.

Um endereço de rua não é garantido. address continha a linha da rua em 22 de 30 resultados, e city, region e zipcode chegam como campos separados ao lado dele. Construa o endereço a partir das partes que você tem.

openState é o estado no momento da chamada. Ele diz closed ou Open 24 hours para o momento em que a solicitação foi executada, então é um instantâneo em vez de uma propriedade da empresa. workingHours é o campo durável.

A paginação é por URL, e uma consulta pode demorar. pagination.totalPages chegou a 17 para uma cidade e uma palavra-chave, com 30 resultados por página. O custo escala com as páginas, então restrinja a palavra-chave antes de percorrê-las todas.

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

Preços, plano gratuito e limites

Cada ferramenta do Yellow Pages custa 10 créditos por chamada bem-sucedida. O tamanho da resposta não muda o preço, então uma página de 30 empresas custa o mesmo que um detalhe de anúncio.

O plano gratuito é 1.000 créditos todo mês sem cartão, o que equivale a 100 chamadas ao Yellow Pages na taxa base. Ele renova com o ciclo de cobrança, então um agente de baixo volume roda no plano gratuito indefinidamente.

Os 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 plano gratuito permite 1 solicitação por vez, o Startup 15, o Business 30, o Growth 50, e os planos de alto volume vão de 200 a 1.500. Tente novamente no 429 com um backoff em qualquer coisa não supervisionada, porque um agente que enriquece uma página de empresas atingirá o teto antes de você.

Uma solicitação que retorna não-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 lhe dá. Um nicho e uma cidade vão para a ferramenta de busca, e uma URL do Yellow Pages vai direto para a ferramenta de local.

Depois pese o enriquecimento. O resultado da busca já carrega nome, telefone, endereço, categorias, horários, selos e, onde o Yellow Pages os mostra, a classificação e a contagem de avaliações. Isso cobre uma lista de prospecção, uma contagem de cobertura ou uma comparação de classificações em uma chamada. A ferramenta de local adiciona a descrição, a lista de serviços, as marcas e as fotos, e custa uma chamada por empresa, então 30 empresas enriquecidas custam 300 créditos contra os 10 que a página custou.

Ordene no servidor quando a pergunta for sobre ordem. sort: averageRating é um parâmetro, onde puxar várias páginas para ordenar localmente são várias chamadas.

Comparação

O Yellow Pages não tem API pública, então as alternativas realistas são as duas grandes APIs de dados locais.

A linha que decide é o que um anúncio diz sobre si mesmo. Google e Yelp retornam um registro estruturado, e o Yellow Pages retorna o texto que um contratante escreveu sobre seus próprios serviços, marcas e condições de pagamento, que é a parte sobre a qual uma lista de prospecção de ofícios é construída. Para cobertura, precisão de horários e categorias de consumo, o Google Places é a fonte mais forte.

FAQ

Existe um servidor MCP oficial do Yellow Pages?

Yellow Pages não publica uma, e também não publica uma API pública. Esta é mantida pela HasData e lê listagens públicas do Yellow Pages.

O que é um servidor MCP do Yellow Pages?

Um servidor MCP expõe ferramentas que um cliente de IA pode chamar. Este transforma buscas e listagens do Yellow Pages em JSON que um agente pode analisar, sem precisar de navegador ou biblioteca de scraping na sua stack.

Preciso de uma conta no Yellow Pages?

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

Quais países são cobertos?

Os EUA em www.yellowpages.com e o Canadá em www.yellowpages.ca. Passe domain para alternar.

Por que um campo está ausente em alguns resultados?

Porque o Yellow Pages mostra o que cada empresa preencheu ou pagou. Uma avaliação apareceu em 11 de 30 resultados na nossa amostra e um endereço em 22. Trate tudo, exceto nome, telefone, URL e categorias, como opcional.

Como obtenho uma contagem de avaliações?

A partir do resultado da busca, onde reviews é uma contagem. O ratings.reviews da ferramenta de local espelha a avaliação em vez de contar as avaliações, então não é o campo para isso.

Posso usar isso junto com outras APIs da HasData?

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

A HasData é afiliada ao Yellow Pages?

Não. A HasData é um serviço independente e não é afiliada, endossada ou patrocinada pela Thryv ou pela marca Yellow Pages. Yellow Pages é uma marca registrada de seu respectivo proprietário. As ferramentas funcionam apenas com dados publicamente disponíveis, e você é responsável por usar os resultados em conformidade com os termos do site e a lei aplicável a você.

Conformidade e dados pessoais

Estas listagens são registros comerciais, e o uso óbvio é uma lista de leads. É aí que o cuidado é necessário, porque ligar e enviar mensagens para os números de telefone que você coleta é regulamentado separadamente da coleta. Nos EUA, o TCPA rege chamadas e mensagens para esses números, inclusive para empresas em vários aspectos, e as regras de telemarketing da FTC se aplicam adicionalmente. A listagem de um profissional autônomo também pode conter seu próprio nome e número de celular, o que a torna tanto um dado pessoal quanto um registro comercial. Coletar a lista é a parte fácil, então verifique o que você pode fazer com ela antes de montar o alcance.

Links da HasData

• API de Scraper do Yellow Pages, 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 Maps, Yelp, Google Search, Google Trends, Google Flights, DuckDuckGo, YouTube, TikTok, Instagram, Amazon, Walmart, Shopify, Zillow, Redfin, Airbnb, Booking.com, Indeed, Glassdoor.

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 das ferramentas, a parte que pode quebrar sem um commit aqui. Eles verificam que ?apis=yellowpages retorna a contagem esperada de ferramentas, que nenhum nome mudou, que toda ferramenta ainda declara seus parâmetros obrigatórios e traz uma descrição, que sort ainda oferece as quatro ordens, e que a chave em uso é realmente aceita. Esse último teste chama uma ferramenta de verdade e custa 10 créditos, que é o preço de um canário que pode falhar pelo motivo certo.

Um teste verifica que uma busca ao vivo ainda traz uma contagem real de avaliações nos resultados que a possuem. O README envia os leitores para a ferramenta de busca para esse número justamente porque a ferramenta de local não o fornece, e o conselho só se mantém enquanto o campo existir.

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 corresponda à realidade merece uma issue. Há um modelo exatamente para isso. Pull requests são bem-vindos para o mesmo, e para qualquer coisa no lançador.

Licença

MIT, veja LICENSE.