API ВЕГА

Yellow Pages MCP Server

Размещённый сервер Model Context Protocol (MCP), который предоставляет Claude, Cursor, Windsurf и любому другому MCP-клиенту два инструмента Yellow Pages только для чтения. Ищите местные компании по ключевому слову и местоположению, а затем просматривайте полную информацию об отдельной организации: телефон, часы работы, услуги и фотографии — в структурированном формате JSON. Размещать сервер самостоятельно не нужно.

Сервер получает общедоступные сведения из объявлений Yellow Pages, доступные посетителям без входа на yellowpages.com и yellowpages.ca.

Каждый месяц предоставляется 1 000 бесплатных кредитов без необходимости привязывать карту — этого хватит на 100 вызовов Yellow Pages по тарифу 10 кредитов за вызов.

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

Содержание

  • Требования

  • Быстрый старт

  • Примеры запросов

  • Инструменты

  • Ошибки и возможные сбои

  • Стоимость, бесплатный тариф и ограничения

  • Выбор инструмента

  • Сравнение с аналогами

  • Часто задаваемые вопросы

  • Ссылки HasData

  • Разработка

  • Участие в проекте

  • Лицензия

Требования

Вам понадобится MCP-клиент и API-ключ HasData из панели управления. Его можно получить бесплатно, без привязки карты. Бесплатный тариф покрывает около 100 вызовов в месяц при стоимости 10 кредитов за вызов. Это удалённый сервер, поэтому для подключения достаточно URL и заголовка x-api-key — запускать контейнер не нужно. Клиент, который поддерживает только stdio, может подключиться к серверу через небольшой запускающий модуль. Он опубликован в npm как @hasdata/yellowpages-mcp, а в PyPI — как hasdata-yellowpages-mcp. Настройка приведена ниже.

Быстрый старт

URL сервера одинаков для всех клиентов. Мы проверили подключение в Claude Code и Claude Desktop. Примеры для остальных клиентов соответствуют их документированному формату удалённого сервера.

ПолеЗначение
URLhttps://mcp.hasdata.com/mcp?apis=yellowpages
ТранспортHTTP, потоковый
Заголовок авторизацииx-api-key: HASDATA_API_KEY

Клиенты с поддержкой OAuth можно подключить по тому же URL и авторизовать без добавления ключа в файл конфигурации.

Claude Code

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

Claude Desktop

Откройте Settings, затем Connectors, выберите Add custom connector, вставьте https://mcp.hasdata.com/mcp?apis=yellowpages и выполните вход.

Если вы настраиваете подключение через файл конфигурации, учтите, что Claude Desktop загружает только локальные серверы stdio. Поэтому для подключения к удалённому серверу потребуется запускающий модуль stdio. Эту функцию выполняет пакет @hasdata/yellowpages-mcp: он считывает ключ из переменной окружения. Добавьте следующий блок в claude_desktop_config.json:

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

Если вместо Node вы используете Python, замените запускающий модуль на пакет из PyPI. Команда uvx запускает его без предварительной установки:

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

Cursor

Добавьте настройки в ~/.cursor/mcp.json, чтобы использовать сервер во всех проектах, или в .cursor/mcp.json — чтобы подключить его только в одном:

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

Windsurf

Файл конфигурации: ~/.codeium/windsurf/mcp_config.json. В Windsurf поле называется serverUrl, а не url:

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

VS Code

Добавьте конфигурацию в .vscode/mcp.json в рабочей области:

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

Примеры запросов

Каждый из этих запросов вызывает один инструмент. В некоторых случаях последовательно вызываются два инструмента, если второму нужен URL, возвращённый первым.

  • Найди сантехников в Остине, штат Техас, и расположи их в порядке убывания рейтинга с учётом количества отзывов.

  • Перечисли всех подрядчиков по HVAC в этом почтовом индексе, у которых указаны телефон и часы работы.

  • Какие из этих компаний работают более 20 лет?

  • Изучи это объявление в Yellow Pages и перечисли бренды, с которыми работает компания.

  • Получи вторую и третью страницы со списками кровельщиков в Остине и объедини результаты в один список.

  • Отсортируй стоматологов в этом городе по среднему рейтингу, а не по релевантности.

Запрос с указанием специализации и города направляется инструменту поиска. Чтобы получить сведения об услугах, брендах и способах оплаты, нужен отдельный вызов для каждой компании. Поэтому для составления списка потенциальных клиентов используйте инструмент поиска, а для обогащения данных — инструмент получения информации об организации.

Инструменты

ИнструментВозвращаемые данные
hasdata_yellowpages_place_getPlaceDetailsИзвлекает данные одной организации из объявления Yellow Pages по URL и возвращает название, полный адрес, телефон, сайт, категории, срок работы, часы работы, рейтинги и другие сведения. 10 кредитов за вызов
hasdata_yellowpages_search_getSearchResultsВозвращает сведения о каждой компании: название, URL объявления, телефон, адрес, категории, рейтинг, количество отзывов и срок работы. 10 кредитов за вызов

Доступны два инструмента. Каждый успешный вызов стоит 10 кредитов.

Получение результатов поиска Yellow Pages

hasdata_yellowpages_search_getSearchResults

Инструмент возвращает страницу со списком компаний, найденных по ключевому слову и местоположению. На одной странице — до 30 компаний.

ПараметрТипОбязательныйПримечания
keywordstringдаПоисковый запрос, например plumber
locationstringдаМестоположение, например Austin, TX
sortstringdefault, distance, averageRating или name
domainstringwww.yellowpages.com или www.yellowpages.ca
pagenumberНомер страницы результатов, начиная с 1

В ответе содержится объект searchInformation с исходным запросом и значением totalResults, массив organicResults и объект pagination с полями currentPage, totalPages, perPage, nextPageUrl и otherPageUrls.

Почти все поля результата необязательны: Yellow Pages отображает только те сведения, за заполнение или размещение которых заплатила компания. В примере с 30 результатами поля title, phone, url, categories, country и position присутствовали у всех компаний, address — у 22, rating и reviews — у 11, а contactUs — у 5. Обрабатывайте результаты с учётом того, что их структура может различаться.

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

Получение подробной информации об организации в Yellow Pages

hasdata_yellowpages_place_getPlaceDetails

Инструмент возвращает полные сведения об одном объявлении по его URL в Yellow Pages.

ПараметрТипОбязательныйПримечания
urlstringдаURL объявления, возвращённый инструментом поиска

Результат состоит из четырёх блоков, а не из одного объекта с плоской структурой.

В overview повторяются название, местоположение, телефон, часы работы, отметки и сайт. Кроме того, блок содержит поле paymentAccepted и массив breadcrumbs, показывающий положение объявления в таксономии Yellow Pages. В блоке ratings указан звёздный рейтинг. В details содержится подробное описание, предоставленное компанией. Массив images содержит URL фотографий.

Основная ценность для обогащения данных — в блоке details. Его содержимое представлено не массивами, а текстом с элементами, разделёнными запятыми. Поле generalInfo содержит описание компании, servicesProducts — перечень услуг, brands — бренды, с которыми она работает, paymentMethod — способы оплаты, а categories — полный список категорий в виде одной строки.

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

Ошибки и нештатные ситуации

Учитывайте возможные ошибки и нештатные ситуации, а не исходите из того, что всё будет работать идеально.

Количество отзывов берите из результатов поиска, а не из сведений о компании. В результатах инструмента поиска поля rating и reviews содержат ожидаемые значения, например 2.87 и 15. В инструменте сведений о компании поле ratings.reviews во всех проверенных объявлениях совпадало с ratings.rating, поэтому оно не содержит количество отзывов. Берите это число из результатов поиска, а затем дополняйте данные сведениями о компании.

В ответе инструмента сведений о компании поле ratings может отсутствовать. В одном из четырёх полученных объявлений этого блока не было вовсе, даже в пустом виде.

Поля details — это строки со значениями, разделёнными запятыми, а тип categories различается в зависимости от инструмента. В результатах поиска categories — массив. В details категории представлены одной строкой. Если вам нужен список, разделите строку по запятым и учитывайте, что в названии отдельной категории может быть запятая.

Поле website иногда содержит ссылку на Yellow Pages. В нескольких объявлениях вместо сайта компании указана отслеживаемая ссылка на yellowpages.com. Перед переходом по такой ссылке или сохранением проверьте домен.

Срок работы компании — это значок, а не отдельное поле. В badges встречаются две разные разновидности сведений: сколько лет компания работает, например "40 Years in Business", и сколько лет она платит Yellow Pages, например "11 Years with Yellow Pages". Ориентируйтесь на текст, а не на первое число.

Улица в адресе может отсутствовать. В поле address улица была указана в 22 из 30 результатов. Поля city, region и zipcode передаются отдельно. Составляйте адрес из доступных частей.

openState показывает состояние на момент вызова. Поле содержит значение closed или Open 24 hours в зависимости от времени выполнения запроса, поэтому это моментальный снимок, а не постоянная характеристика компании. Для стабильных данных используйте workingHours.

Разбиение на страницы выполняется по URL, а обработка запроса может занять много времени. Для одного города и одного ключевого слова значение pagination.totalPages достигало 17 при 30 результатах на странице. Стоимость растёт с количеством страниц, поэтому перед их просмотром уточните ключевое слово.

В результатах с данными также есть requestMetadata.id — его стоит указывать при обращении в службу поддержки.

Стоимость, бесплатный уровень и лимиты

Каждый вызов инструмента Yellow Pages стоит 10 кредитов при успешном выполнении. Размер ответа на стоимость не влияет: страница с 30 компаниями стоит столько же, сколько сведения об одном объявлении.

Бесплатный уровень — 1 000 кредитов в месяц без привязки карты, то есть 100 вызовов Yellow Pages по базовой ставке. Кредиты обновляются с началом нового расчётного периода, поэтому агент с небольшим объёмом запросов может пользоваться бесплатным уровнем постоянно.

Платные планы начинаются от $59 в месяц за 200 000 кредитов, то есть за 20 000 вызовов. При увеличении объёма цена за единицу снижается: с $2.95 за 1 000 вызовов на начальном плане до $1.19 на Basic и $0.83 на планах Growth. Актуальные цены указаны на странице с тарифами.

План также определяет количество параллельных запросов. Бесплатный уровень допускает 1 запрос одновременно, Startup — 5, Basic — 15, а на планах Growth лимит составляет от 50 до 500. Для автоматических процессов при ответе 429 используйте повторные попытки с увеличивающимся интервалом: агент, который дополняет данные для страницы с компаниями, достигнет лимита раньше, чем вы.

Запрос, завершившийся ответом с кодом, отличным от 200, не тарифицируется. Успешный вызов, даже если он не нашёл результатов, всё равно считается вызовом.

Выбор инструмента

Отталкивайтесь от того, что указано в запросе. Если даны ниша и город, используйте инструмент поиска; если указан URL Yellow Pages — сразу инструмент сведений о компании.

Затем оцените, насколько нужны дополнительные сведения. Результаты поиска уже содержат название, телефон, адрес, категории, часы работы, значки и, если Yellow Pages указывает их, рейтинг и количество отзывов. Этого достаточно, чтобы за один вызов составить список потенциальных клиентов, оценить охват или сравнить рейтинги. Инструмент сведений о компании добавляет описание, список услуг, бренды и фотографии. Он выполняет отдельный вызов для каждой компании: дополнение данных для 30 компаний обойдётся в 300 кредитов, тогда как сама страница результатов стоит 10.

Если важен порядок результатов, сортируйте их на стороне сервера. Для этого достаточно одного параметра — sort: averageRating; загрузка нескольких страниц для последующей сортировки на вашей стороне потребует нескольких вызовов.

Сравнение с альтернативами

У Yellow Pages нет общедоступного API, поэтому реалистичные альтернативы — два крупных API локальных данных.

Google Places APIYelp Fusion APIЭтот сервер
Условия доступаПроект Google Cloud с оплатойОдобренное приложение разработчикаКлюч API
Услуги и брендыНе возвращаютсяНе возвращаютсяБлок details
Способы оплатыНе возвращаютсяЧастично, в виде атрибутовКак указано в объявлении
Срок работы компанииНе возвращаетсяНе возвращаетсяВ badges
ФотографииЧерез отдельный платный вызовВключеныМассив URL
КанадаПоддерживаетсяПоддерживаетсяyellowpages.ca
ОхватСамый широкийПреимущественно потребительский сегментРемесленные услуги и сервисы

Решающим фактором становится то, что объявление сообщает о компании. Google и Yelp возвращают структурированные записи, а Yellow Pages — описание, которое подрядчик написал о своих услугах, брендах и условиях оплаты. Именно такие сведения нужны для списка потенциальных клиентов в сфере ремесленных услуг. Если важны охват, точность часов работы и потребительские категории, более надёжным источником будет Google Places.

Часто задаваемые вопросы

Есть ли официальный MCP-сервер Yellow Pages?

Yellow Pages не публикует ни MCP-сервер, ни общедоступный API. Этот сервер поддерживается HasData и получает данные из общедоступных объявлений Yellow Pages.

Что такое MCP-сервер Yellow Pages?

MCP-сервер предоставляет инструменты, которые может вызывать AI-клиент. Этот сервер преобразует результаты поиска и объявления Yellow Pages в JSON, с которым может работать агент, — без браузера и библиотек для сбора данных в вашем стеке.

Нужна ли учётная запись Yellow Pages?

Нет. Для работы нужен только ключ HasData.

Какие страны поддерживаются?

США — www.yellowpages.com, Канада — www.yellowpages.ca. Чтобы переключить домен, передайте параметр domain.

Почему в некоторых результатах нет отдельных полей?

Потому что сведения в Yellow Pages зависят от того, что указала или за что заплатила каждая компания. В нашей выборке рейтинг присутствовал в 11 из 30 результатов, а улица в адресе — в 22. Считайте необязательными все поля, кроме названия, телефона, URL и категорий.

Как получить количество отзывов?

Возьмите его из результатов поиска: поле reviews содержит количество. В инструменте сведений о компании значение ratings.reviews повторяет рейтинг, а не считает отзывы, поэтому это не то поле, которое вам нужно.

Можно ли использовать этот сервер вместе с другими API HasData?

Да. Один ключ подходит для всех API, а все они доступны через один endpoint с помощью параметра apis. Укажите ?apis=yellowpages,google_maps, чтобы получить наборы инструментов для обоих сервисов в одном подключении, или перейдите на mcp.hasdata.com/api/mcp, чтобы посмотреть полный каталог.

Связана ли HasData с Yellow Pages?

Нет. HasData — независимый сервис, не связанный с Thryv или брендом Yellow Pages и не одобренный и не спонсируемый ими. Yellow Pages — товарный знак соответствующего владельца. Инструменты работают только с общедоступными данными. Вы несёте ответственность за использование результатов в соответствии с условиями сайта и применимым законодательством.

Соблюдение требований и персональные данные

Эти объявления содержат сведения о компаниях, а очевидный вариант использования — составление списка потенциальных клиентов. Именно здесь важно соблюдать осторожность: правила сбора контактных данных и совершения звонков или отправки сообщений на собранные номера различаются. В США звонки и сообщения на такие номера, в том числе в ряде случаев деловым абонентам, регулируются законом TCPA; кроме того, применяются правила FTC для телемаркетинга. В объявлении индивидуального предпринимателя могут быть указаны его имя и мобильный номер — это уже персональные данные, даже если они размещены в сведениях о компании. Собрать список просто, поэтому прежде чем начинать рассылку или обзвон, выясните, что именно разрешено делать с этими данными.

Ссылки HasData

Другие MCP-серверы HasData: Google Maps, Yelp, Google Search, Google Trends, Google Flights, DuckDuckGo, YouTube, TikTok, Instagram, Amazon, Walmart, Shopify, Zillow, Redfin, Airbnb, Booking.com, Indeed, Glassdoor.

Разработка

Запускатель — это простой мост stdio к удалённому серверу, поэтому сборка не требуется.

npm install
HASDATA_API_KEY=your_key_here npm test

Тесты в test/ проверяют контракт инструментов — ту часть, которая может измениться без коммита в этом репозитории. Они проверяют, что ?apis=yellowpages возвращает ожидаемое количество инструментов, их названия не изменились, каждый инструмент по-прежнему объявляет обязательные параметры и содержит описание, sort предлагает четыре варианта сортировки, а используемый ключ действительно принимается. Последняя проверка в реальности вызывает инструмент и расходует 10 кредитов — такова цена контрольного теста, который должен завершаться сбоем, если обнаружит проблему.

Один из тестов проверяет, что в результатах актуального поиска по-прежнему указано реальное количество отзывов, если эти данные доступны. В README читателям рекомендуют обращаться за этим числом к инструменту поиска именно потому, что инструмент для мест его не возвращает. Эта рекомендация остаётся верной, только пока поле с количеством отзывов присутствует в результатах.

Набор тестов контракта также запускается по расписанию раз в неделю: список инструментов на стороне сервиса может измениться, даже если в этом репозитории ничего не менялось.

Участие в разработке

Если таблица инструментов, пример ответа или описание поведения не соответствуют действительности, сообщите об этом в issue. Для таких случаев предусмотрен специальный шаблон. Будем рады pull request с исправлениями, а также с любыми изменениями в запускателе.

Лицензия

MIT; подробности см. в файле LICENSE.