Yandex Audience MCP

Яндекс Аудитории MCP

A1 Яндекс Аудитории MCP подключает AI-приложение к сегментам, пикселям и доступам Яндекс Аудиторий. Попросите на естественном языке показать, что уже есть в аккаунте, подготовить сегмент из CRM, собрать похожую аудиторию или выдать доступ коллегам — ассистент выполнит это через ваш аккаунт. Подключение начинается прямо в диалоге: не нужно заранее создавать токен или редактировать конфигурацию.

• 20 инструментов. Сегменты, пиксели, доступы, подключение аккаунта и дополнительный прямой вызов API.
• Подключение в чате. Яндекс откроет страницу входа; одноразовый код действует 10 минут, а сервер проверит доступ к сегментам сразу после подключения.
• CRM и идентификаторы. CSV с email и телефонами, а также TSV/TXT с device ID, MAC-адресами или SHA256-хешами.
• Два шага для сегмента из файла. Сначала загрузка, затем отдельное подтверждение параметров и запуск обработки.
• Без глобальной установки. Пакет запускается через npx на Node.js 20+ и подключается к AI-клиенту по stdio.

Попробуйте первым сообщением:

Покажи мои сегменты в Яндекс Аудиториях: названия, типы и текущие статусы.

Подключить сервер · Посмотреть сценарии · Открыть техническую документацию

Увидеть работу за минуту

Вы: Подключи Яндекс Аудитории.

Ассистент: Даёт ссылку на вход в Яндекс. Откройте её под аккаунтом, которому принадлежат нужные сегменты (или которому они доверены), подтвердите доступ и пришлите показанный код.

Вы: Отправляет код со страницы Яндекса.

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

Вы: Загрузи buyers.csv как CRM-сегмент «Покупатели 2026» и остановись после загрузки.

Ассистент: Загружает файл — в аккаунте появляется сегмент со статусом uploaded, показывает его id, имя и параметры и ждёт отдельного подтверждения. После подтверждения обработка идёт не мгновенно, поэтому статус проверяется через список сегментов.

Содержание

• Быстрый старт
• Что можно поручить
• Как это работает
• Что может изменить данные
• Подключение и настройка
• Данные и телеметрия
• Ограничения
• Техническая документация
• Поддержка

クイックスタート

Node.js 20 以降と、Yandex Audiences のアカウントが必要です。サーバーは npx で起動するため、パッケージを別途インストールする必要はありません。トークンは事前に用意する必要はありません。接続は対話中に行います。CI では有効なトークンを設定できます。詳しくは接続と設定をご覧ください。

1. AI アプリにサーバーを追加します。以下には Codex の例が表示されており、その他のアプリの手順は折りたたみ式の説明にまとめられています。
2. 「Yandex Audiences に接続して」と入力します。アシスタントが Yandex へのログインを案内し、セグメントへのアクセスを確認します。
3. 「Yandex Audiences のセグメントを、名前、種類、現在のステータスとともに表示して」のような、安全なリクエストから始めましょう。

codex mcp add yandex-audience -- npx -y mcp-yandex-audience@latest

codex mcp list

claude mcp add --transport stdio --scope user yandex-audience -- npx -y mcp-yandex-audience@latest

claude mcp list

{
  "mcpServers": {
    "yandex-audience": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-audience@latest"]
    }
  }
}

{
  "mcpServers": {
    "yandex-audience": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-audience@latest"]
    }
  }
}

{
  "servers": {
    "yandex-audience": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-audience@latest"]
    }
  }
}

依頼できること

アカウントにすでにあるものを確認する

• セグメント、その種類、ステータス、ID を確認する。
• 処理中のセグメント、エラーになったセグメント、データが不足しているセグメントを見つける。
• ピクセルと、過去 7 日、30 日、90 日のリーチ、およびそれらをもとに作成したセグメントを確認する。
• 特定のセグメントへのアクセス権が付与されている相手を確認する。

CRM からセグメントを準備する

• email、phone、ext_id、または external_id 列を含む CSV をアップロードする。
• デバイス ID、MAC アドレス、または SHA256 ハッシュを含む TSV/TXT をアップロードする。
• 確認前に、アップロードしたセグメントの設定を確認する。
• 必要な名前とデータの種類を指定してセグメントを保存し、処理状況を確認する。

Собрать новую аудиторию

• Создать похожую аудиторию на основе существующего сегмента: от более похожей и узкой до более широкой.
• Собрать сегмент посетителей по пикселю за период от 1 до 90 дней.
• Добавить к пиксельному сегменту условия по числу срабатываний и UTM-меткам.

Работать с пикселями и доступами

• Создать или переименовать пиксель.
• Выдать коллеге или агентству доступ к сегменту: только просмотр или редактирование.
• Отозвать доступ, когда он больше не нужен.

Использовать дополнительные возможности API

raw_request нужен для операций, у которых пока нет отдельного инструмента: например, повторной обработки сегмента или восстановления пикселя. Это инструмент для технических специалистов: он может выполнить запись или удаление, поэтому для обычных задач лучше использовать отдельные команды выше.

Полные входные параметры, ответы и статусы собраны в справочнике инструментов.

Как это работает

Сервер работает с тремя сущностями Яндекс Аудиторий:

Сегмент из файла создаётся в два шага:

1. Вы передаёте CSV, TSV или TXT-файл — путь к локальному файлу или его содержимое, но не оба источника одновременно. Сервер загружает файл в Яндекс Аудитории, и в аккаунте появляется объект со статусом uploaded.
2. Отдельной командой вы подтверждаете имя, тип данных и параметры обработки. Только после этого Яндекс Аудитории начинают обработку.

Готовность появляется не мгновенно: сервер проверяет статус через список сегментов, где возможны состояния обработки, ошибки или недостаточного объёма данных. Для CRM используйте CSV с заголовками email, phone, ext_id или external_id. Для хешированных данных API принимает SHA256; MD5 не поддерживается.

Сервер не управляет рекламными кампаниями, ставками и объявлениями в Яндекс Директе. Готовый сегмент подключается к кампании вне этого MCP-сервера.

Что может изменить данные

Яндекс Аудитории — API с операциями записи. MCP-сервер передаёт AI-клиенту информацию о том, какие инструменты читают, изменяют или удаляют данные, но правила подтверждения задаёт само AI-приложение.

Сервер не объединяет загрузку файла и подтверждение в один скрытый вызов. При сетевой ошибке или ответе сервера 5xx он не повторяет операции записи автоматически: операция могла уже выполниться. В такой ситуации сначала проверьте состояние через список сегментов, пикселей или доступов.

Подключение и настройка

Для обычного использования токен заранее не нужен:

1. В чате попросите подключить Яндекс Аудитории.
2. Откройте ссылку на Яндекс OAuth под аккаунтом, которому принадлежат нужные сегменты (или которому они доверены).
3. Подтвердите доступ и пришлите код ассистенту. Он одноразовый, действует 10 минут и меняется на токен только внутри работающего сервера.

Сервер использует PKCE: код из чата сам по себе нельзя обменять на токен. Полученный токен хранится локально в ~/.config/mcp-yandex-audience/credentials.json с правами только для владельца, а доступ продлевается автоматически. Сервер просит два права — чтение и изменение сегментов Аудиторий; кампании, объявления и остальные сервисы Яндекса ему недоступны.

Проверить состояние — попросите «покажи статус подключения к Аудиториям», отключить — «отключи Аудитории». Выданный приложению доступ отзывается в Яндекс ID.

Для CI и нестандартных установок доступна настройка через переменные окружения:

Готовый токен для YANDEX_AUDIENCE_TOKEN можно получить через собственное OAuth-приложение:

1. Зарегистрируйте приложение на oauth.yandex.ru/client/new.
2. Выберите права Яндекс Аудиторий: создание сегментов и изменение параметров своих и доверенных сегментов и чтение параметров своих и доверенных сегментов.
3. Получите OAuth-токен — для разработки подойдёт инструкция по отладочному токену — и передайте его серверу в YANDEX_AUDIENCE_TOKEN.

Токен привязан к аккаунту Яндекса: сервер увидит только собственные и доверенные сегменты владельца токена. Такой токен хранится открытым текстом в конфигурации AI-клиента — относитесь к нему как к паролю и не добавляйте конфигурацию с реальным токеном в Git. Подробнее — в официальной документации по авторизации API Яндекс Аудиторий.

Данные и телеметрия

Сервер запускается на вашей машине и обращается к api-audience.yandex.ru напрямую. OAuth-токен добавляется только к запросам Audience API — даже raw_request принимает относительный путь, а переход на посторонний хост блокируется. При входе из диалога сервер дополнительно ходит на oauth.yandex.ru, чтобы обменять код подтверждения и продлевать доступ; при загрузке через file_path читает указанный локальный файл и передаёт его в Яндекс Аудитории.

По умолчанию сервер отправляет на usage.gistrec.cloud анонимную техническую телеметрию: запуск сервера (в том числе без настроенного токена), имя вызванного инструмента и код причины проблемы с конфигурацией — вместе со случайным идентификатором установки, версией пакета, именем и версией AI-клиента, версией Node.js и операционной системой. OAuth-токен, данные аккаунта, содержимое файлов, аргументы инструментов и тексты запросов не читаются и не отправляются. Отправка выполняется в фоне с таймаутом 2 секунды и не влияет на работу сервера; реализация находится в src/telemetry.ts.

Чтобы отключить телеметрию, задайте переменную окружения:

ASKADS_TELEMETRY=0

Ограничения

• Обработка не мгновенная. После подтверждения сегмента проверяйте его состояние через список сегментов: возможны статусы обработки, ошибки и недостаточного объёма данных.
• Удаление сегмента необратимо. Для пикселя API предусматривает восстановление отдельным методом, доступным через raw_request.
• Один сегмент нельзя запросить отдельно. API возвращает общий список — сервер находит нужный сегмент по id в нём.
• Минимум 100 записей и максимум 1 ГБ. При подтверждении меньшего сегмента можно передать check_size: false, но такой сегмент нельзя использовать в Директе, пока размер не вырастет.
• Квоты API. До 30 запросов в секунду с IP и 5 000 запросов в сутки на логин. Создание и изменение сегментов: до 10 в минуту, 100 в час и 500 в сутки. Ошибочные запросы тоже расходуют квоту.
• При временном ограничении API. Сервер повторяет запрос с задержкой до числа попыток из YANDEX_AUDIENCE_MAX_RETRIES; ответ 429 не означает, что нужно создавать объект заново.
• Нет фонового наблюдения. Сервер работает только во время вызова из AI-приложения и сам не ждёт завершения обработки. Если ваше приложение поддерживает задания по расписанию, настройте периодическую проверку статусов через список сегментов.

Техническая документация

• Каталог MCP-возможностей — страницы по пользовательским задачам для каждого инструмента.
• Все инструменты — входные данные, ответы, статусы и ограничения.
• Разработка — локальный запуск, тесты, сборка и read-only smoke-проверка.
• Публикация — выпуск npm-пакета и листинг в каталогах MCP.
• npm-пакет — опубликованная версия mcp-yandex-audience.
• API Яндекс Аудиторий — официальная документация.

Поддержка

Нашли ошибку или не хватает сценария? Создайте issue или напишите в Telegram.