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 或更高版本，以及 Яндекс Аудиторий 账号。服务器通过 npx 启动，因此无需单独安装软件包。无需提前准备令牌——连接可直接在对话中完成；CI 可设置现成令牌，参见连接与配置。

1. 将服务器添加到 AI 应用中——下方展开的是 Codex 示例，其他应用的说明已折叠。
2. 输入：“连接 Яндекс Аудитории。”助手会引导你登录 Яндекс，并检查你对细分受众的访问权限。
3. 从安全的请求开始，例如：“显示我在 Яндекс Аудиториях 中的细分受众：名称、类型和当前状态。”

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

可以交给它做什么

检查账号中已有的内容

• 查看细分受众及其类型、状态和标识符。
• 查找仍在处理、处理失败或数据不足的细分受众。
• 查看像素、过去 7、30 和 90 天的覆盖人数，以及基于这些像素创建的细分受众。
• 查询哪些人获得了特定细分受众的访问权限。

从 CRM 准备细分受众

• 上传包含 email、phone、ext_id 或 external_id 列的 CSV 文件。
• 上传包含设备标识符、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.