# Yandex Audience MCP

**Category:** 👤 Customer Data Platforms  
**Repository:** https://github.com/A1-x-Tech/mcp-yandex-audience  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/yandex-audience-mcp

## Description
MCP server for Yandex Audience API: segments (CRM, lookalike, pixel), pixels, grants.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

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

## Documentation & README

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

[![npm](https://img.shields.io/npm/v/mcp-yandex-audience)](https://www.npmjs.com/package/mcp-yandex-audience)
[![CI](https://github.com/A1-x-Tech/mcp-yandex-audience/actions/workflows/ci.yml/badge.svg)](https://github.com/A1-x-Tech/mcp-yandex-audience/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

<img src="./assets/a1-logo.svg" alt="A1" width="22">&nbsp;**Яндекс Аудитории MCP** — MCP-сервер, с которым Claude, Cursor, Codex и другие AI-клиенты управляют сегментами, пикселями и доступами в [Яндекс Аудиториях](https://audience.yandex.ru) по обычной команде. Он уже знает двухфазную загрузку файлов, схемы 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` сохраняет его с выбранным именем и типом данных, после чего начинается асинхронная обработка.

[Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть справочник инструментов](docs/TOOLS.md)

---

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

> **Вы:** Покажи все сегменты, которые ещё обрабатываются или завершились ошибкой.
>
> **Ассистент:** Получу список и отберу статусы `uploaded`, `is_processed`, `processing_failed` и `few_data`. Ничего не изменяю.
>
> **Вы:** Загрузи `buyers.csv` как CRM-сегмент «Покупатели 2026». Файл не хеширован. Остановись перед подтверждением.
>
> **Ассистент:** Выполню только загрузку и верну id. Перед `confirm_segment` покажу имя, `content_type: crm`, признак `hashed: false` и попрошу отдельную команду.
>
> **Вы:** Подтверждай и потом проверь статус.
>
> **Ассистент:** Сохраню сегмент и проверю его через `list_segments`. Обработка идёт асинхронно, поэтому верну текущий статус, а не буду обещать готовность заранее.

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

---

## Содержание

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

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

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

1. [Получите OAuth-токен](#получение-доступа-к-api).

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

   ```bash
   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-клиенты»](#установка-в-другие-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` помечен как разрушительный инструмент.** Он способен выполнять произвольную запись и удаление. Используйте специализированный инструмент, если он уже есть.

Полные входные схемы, статусы и форматы ответов собраны в [справочнике инструментов](docs/TOOLS.md).

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

Яндекс Аудитории — 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>

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

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

</details>

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

<br>

```bash
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\`.

```json
{
  "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` проекта:

```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`:

```json
{
  "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](https://oauth.yandex.ru/client/new).
2. Выберите права Яндекс Аудиторий:
   - создание сегментов и изменение параметров своих и доверенных сегментов;
   - чтение параметров своих и доверенных сегментов.
3. Получите OAuth-токен — для разработки можно использовать инструкцию по [отладочному токену](https://yandex.ru/dev/id/doc/ru/tokens/debug-token).
4. Передайте токен серверу в `YANDEX_AUDIENCE_TOKEN`.

Токен привязан к аккаунту Яндекса. Сервер видит те же собственные и доверенные сегменты, которые доступны владельцу токена. Подробнее — в официальной документации по [авторизации API Яндекс Аудиторий](https://yandex.ru/dev/audience/ru/intro/authorization).

> **Токен хранится открытым текстом в конфигурации 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, добавьте:

```text
ASKADS_TELEMETRY=0
```

Реализация находится в [`src/telemetry.ts`](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-клиента и сам не ждёт завершения обработки между задачами.

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

- [Все инструменты](docs/TOOLS.md) — входные данные, ответы, статусы и ограничения.
- [Разработка](docs/DEVELOPMENT.md) — локальный запуск, тесты, сборка и read-only smoke-проверка.
- [Публикация](docs/PUBLISHING.md) — выпуск npm-пакета и листинг в каталогах MCP.
- [npm-пакет](https://www.npmjs.com/package/mcp-yandex-audience) — опубликованная версия `mcp-yandex-audience`.
- [API Яндекс Аудиторий](https://yandex.ru/dev/audience/) — официальная документация.

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

```bash
npm install
npm run typecheck
npm test
```

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

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

Нашли ошибку или не хватает сценария? [Создайте issue](https://github.com/A1-x-Tech/mcp-yandex-audience/issues) или напишите в Telegram: [@gistrec](https://t.me/gistrec).

## Лицензия

MIT — см. [LICENSE](LICENSE).