Превратите клиентские данные в готовый рекламный сегмент обычной командой

<img src="./assets/a1-logo.svg" alt="A1" width="22"> Яндекс Аудитории MCP — MCP-сервер, с которым Claude, Cursor, Codex и другие AI-клиенты управляют сегментами, пикселями и доступами в Яндекс Аудиториях по обычной команде. Он уже знает двухфазную загрузку файлов, схемы API и границу между подготовкой данных и созданием рабочего сегмента.

• 16 готовых инструментов. 8 для сегментов, 4 для пикселей, 3 для доступов и универсальный raw_request.
• CRM-файлы и идентификаторы. Сервер загружает CSV с email и телефонами, а также TSV/TXT с device ID, MAC-адресами или SHA256-хешами.
• Look-alike и пиксельные сегменты. Ассистент создаёт похожую аудиторию или сегмент пользователей, увидевших баннер, с нужными условиями.
• Явное подтверждение загрузки. Файл сначала получает статус uploaded; имя, тип данных и параметры обработки задаются отдельным вызовом confirm_segment.
• Права без ручной навигации. Можно выдать или отозвать доступ к сегменту по логину Яндекса.
• Без глобальной установки. Пакет запускается через npx на Node.js 20+ и подключается к AI-клиенту по stdio.

Кому подходит: маркетологам и аналитикам, которые уже работают с Яндекс Аудиториями и хотят собирать и обслуживать отдельные сегменты из AI-клиента. Сервер не настраивает рекламные кампании в Директе и не заменяет аккаунт или OAuth-токен Яндекса.

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

Сначала загрузить, затем проверить параметры

Вы: Загрузи clients.csv, но пока не создавай рабочий сегмент.

Ассистент: Загружу файл как CRM-данные и верну id со статусом uploaded. confirm_segment без отдельной команды не вызываю.

Создать look-alike от существующей базы

Вы: Создай похожую аудиторию от сегмента 12345 со степенью похожести 2. Сохрани распределение по устройствам и географии.

Ассистент: Перед созданием проверю исходный сегмент в доступном списке и покажу параметры новой аудитории.

Начать с безопасной проверки

Вы: Покажи мои сегменты, их типы и статусы. Ничего не изменяй.

Ассистент: Вызову только list_segments; загрузка, переименование и удаление не выполняются.

Рабочий сегмент появляется только после подтверждения. upload_segment_file и upload_segment_csv_file передают данные в Яндекс Аудитории, но оставляют сегмент в состоянии uploaded. confirm_segment сохраняет его с выбранным именем и типом данных, после чего начинается асинхронная обработка.

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

---

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

Вы: Покажи все сегменты, которые ещё обрабатываются или завершились ошибкой.

Ассистент: Получу список и отберу статусы uploaded, is_processed, processing_failed и few_data. Ничего не изменяю.

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

Ассистент: Выполню только загрузку и верну id. Перед confirm_segment покажу имя, content_type: crm, признак hashed: false и попрошу отдельную команду.

Вы: Подтверждай и потом проверь статус.

Ассистент: Сохраню сегмент и проверю его через list_segments. Обработка идёт асинхронно, поэтому верну текущий статус, а не буду обещать готовность заранее.

Примеры показывают последовательность доступных инструментов. Состав сегментов, охваты, статусы и доступность операций всегда приходят из вашего аккаунта Яндекс Аудиторий.

---

Содержание

• Быстрый старт
• Что можно поручить
• Где изменяются данные
• Установка в другие AI-клиенты
• Получение доступа к API
• Настройка
• Данные и телеметрия
• Ограничения
• Документация и разработка
• Помощь и обратная связь

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

Нужны Node.js 20+, аккаунт Яндекс Аудиторий и OAuth-токен с правами на чтение и изменение сегментов.

1. Получите OAuth-токен.

2. Добавьте MCP-сервер в Codex:

   codex mcp add yandex-audience \
     --env YANDEX_AUDIENCE_TOKEN=ваш_токен \
     -- npx -y mcp-yandex-audience@latest
   

3. Начните новую задачу Codex и проверьте подключение запросом без записи:

   Покажи мои сегменты в Яндекс Аудиториях и их статусы. Ничего не изменяй.

Для Claude Code, Claude Desktop, Cursor и VS Code готовые конфигурации находятся в разделе «Установка в другие AI-клиенты».

Что можно поручить

Проверить сегменты

• Получить общий список. Увидеть доступные сегменты всех типов, их id, статусы и типовые поля — list_segments.
• Найти незавершённую обработку. Отобрать сегменты со статусами загрузки, обработки, ошибки или недостаточного объёма данных.
• Переименовать сегмент. Изменить только название существующего сегмента — rename_segment.

В API нет отдельного метода чтения одного сегмента. Чтобы найти сегмент по id, ассистент получает список через list_segments и фильтрует его.

Загрузить собственные данные

• CRM-данные. Загрузить CSV с заголовками email, phone, ext_id или external_id — upload_segment_csv_file.
• Идентификаторы. Загрузить TSV/TXT с device ID, MAC-адресами или SHA256-хешами — upload_segment_file.
• Сохранить загруженный сегмент. Отдельно задать имя, content_type, признак хеширования и тип сопоставления устройств — confirm_segment.

Оба инструмента загрузки принимают либо file_path к локальному файлу, либо строку content, но не оба источника одновременно. Сервер не преобразует MD5: API принимает только SHA256.

Расширить или собрать аудиторию по пикселю

• Создать look-alike. Построить похожую аудиторию от исходного сегмента с шириной 1–5 и настройками сохранения распределения — create_lookalike_segment.
• Управлять пикселями. Получить список и охваты за 7, 30 и 90 дней, создать, переименовать или удалить пиксель — list_pixels, create_pixel, update_pixel, delete_pixel.
• Собрать пиксельный сегмент. Выбрать пользователей за период 1–90 дней, добавить условие по частоте и UTM-меткам — create_pixel_segment.

Управлять доступами

• Посмотреть права. Получить список логинов и уровней доступа к сегменту — list_segment_grants.
• Выдать доступ. Добавить для логина право view или edit — add_segment_grant.
• Отозвать доступ. Удалить разрешение пользователя на сегмент — delete_segment_grant.

Вызвать остальные методы API

raw_request вызывает относительный путь Audience Management API. Он нужен для операций, у которых пока нет отдельного инструмента: повторной обработки сегмента, восстановления пикселя, работы с аккаунтами и представителей.

raw_request помечен как разрушительный инструмент. Он способен выполнять произвольную запись и удаление. Используйте специализированный инструмент, если он уже есть.

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

Где изменяются данные

Яндекс Аудитории — write API. Некоторые инструменты только читают данные, другие создают, изменяют или удаляют реальные объекты аккаунта.

Действие	Что происходит	Изменяет аккаунт
list_segments, list_pixels, list_segment_grants	Читает доступные объекты и статусы	Нет
upload_segment_file, upload_segment_csv_file	Загружает файл и создаёт объект со статусом uploaded	Да
confirm_segment	Сохраняет параметры сегмента и запускает обработку	Да
create_lookalike_segment, create_pixel_segment	Создаёт новый сегмент	Да
rename_segment, create_pixel, update_pixel	Создаёт или изменяет объект	Да
add_segment_grant, delete_segment_grant	Выдаёт или отзывает доступ	Да
delete_segment	Удаляет сегмент без возможности восстановления	Да, необратимо
delete_pixel	Удаляет пиксель; восстановление возможно только отдельным методом API	Да

Что сервер делает для снижения риска:

• Не объединяет загрузку файла и confirm_segment в один скрытый вызов.
• Не повторяет автоматически неидемпотентные записи после сетевой ошибки или ответа 5xx.
• Ограничивает raw_request хостом Audience API, чтобы OAuth-токен не ушёл на посторонний адрес.
• Передаёт AI-клиенту MCP-аннотации чтения, записи, идемпотентности и разрушительности.

Поведение подтверждений задаёт AI-клиент, а не MCP-сервер. Для первой проверки явно просите ничего не изменять и начинайте с list_segments или list_pixels.

Установка в другие AI-клиенты

<details open> <summary><strong>Codex</strong></summary>

<br>

codex mcp add yandex-audience \
  --env YANDEX_AUDIENCE_TOKEN=ваш_токен \
  -- npx -y mcp-yandex-audience@latest

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

</details>

<details> <summary><strong>Claude Code</strong></summary>

<br>

claude mcp add yandex-audience \
  -e YANDEX_AUDIENCE_TOKEN=ваш_токен \
  -- npx -y mcp-yandex-audience@latest

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

<br>

Откройте claude_desktop_config.json: на macOS он находится в ~/Library/Application Support/Claude/, на Windows — в %APPDATA%\Claude\.

{
  "mcpServers": {
    "yandex-audience": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-audience@latest"],
      "env": {
        "YANDEX_AUDIENCE_TOKEN": "ваш_токен"
      }
    }
  }
}

</details>

<details> <summary><strong>Cursor</strong></summary>

<br>

Добавьте сервер в ~/.cursor/mcp.json или в .cursor/mcp.json проекта:

{
  "mcpServers": {
    "yandex-audience": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-audience@latest"],
      "env": {
        "YANDEX_AUDIENCE_TOKEN": "ваш_токен"
      }
    }
  }
}

</details>

<details> <summary><strong>VS Code</strong></summary>

<br>

Создайте .vscode/mcp.json. Здесь используется ключ servers, а не mcpServers:

{
  "servers": {
    "yandex-audience": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-audience@latest"],
      "env": {
        "YANDEX_AUDIENCE_TOKEN": "ваш_токен"
      }
    }
  }
}

</details>

Получение доступа к API

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

Токен привязан к аккаунту Яндекса. Сервер видит те же собственные и доверенные сегменты, которые доступны владельцу токена. Подробнее — в официальной документации по авторизации API Яндекс Аудиторий.

Токен хранится открытым текстом в конфигурации AI-клиента. Относитесь к нему как к паролю и не добавляйте конфиг с реальным токеном в Git.

Настройка

Переменная	Обязательна	По умолчанию	Что задаёт
YANDEX_AUDIENCE_TOKEN	да	—	OAuth-токен Яндекса
YANDEX_AUDIENCE_API_HOST	нет	https://api-audience.yandex.ru	Хост API; для международных аккаунтов можно указать .com
YANDEX_AUDIENCE_TIMEOUT_MS	нет	60000	Таймаут одного запроса, мс
YANDEX_AUDIENCE_MAX_RETRIES	нет	3	Повторы при 429; для 5xx и сетевых ошибок — только безопасные GET-запросы
ASKADS_TELEMETRY	нет	включена	0, false, off или no отключает анонимную телеметрию

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

Запросы к Яндекс Аудиториям

Сервер запускается на вашей машине и обращается к api-audience.yandex.ru напрямую. OAuth-токен добавляется только к запросам Audience API. Даже raw_request принимает относительный путь: переход на посторонний хост блокируется.

При загрузке через file_path сервер читает указанный локальный файл и передаёт его в Яндекс Аудитории. Содержимое файла не включается в анонимную телеметрию.

Анонимная телеметрия

По умолчанию сервер отправляет на usage.gistrec.cloud три вида технических событий: запуск сервера, имя вызванного инструмента и код причины неудачного запуска.

В событие входят случайный идентификатор установки, версия пакета, имя и версия AI-клиента, версия Node.js и операционная система. OAuth-токен, данные аккаунта, содержимое файлов, аргументы инструментов и тексты запросов не читаются и не отправляются. Отправка выполняется в фоне с таймаутом 2 секунды и не влияет на работу сервера.

Чтобы отключить телеметрию для MCP-серверов Ask Ads, добавьте:

ASKADS_TELEMETRY=0

Реализация находится в src/telemetry.ts.

Ограничения

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

Документация и разработка

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

Проверить проект локально:

npm install
npm run typecheck
npm test

Тесты не обращаются к сети. npm run smoke — отдельная живая read-only проверка с реальным токеном.

Помощь и обратная связь

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

Лицензия

MIT — см. LICENSE.