Yandex Audience MCP

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

Open source Open in the app JSON README (API)

About

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

Details

Kind: MCP servers
Topic: Productivity
Publisher: a1-x-tech
Origin: official
Category: ferramentas
Transport: local
Version: 1.1.1
Last push: 2026-08-30T13:36:11Z
Repository state: ativo
Language: TypeScript
License: MIT
Added: 2026-08-29 03:01:38
Updated: 2026-08-29 03:01:38
Origin id: io.github.A1-x-Tech/mcp-yandex-audience

README

# <img src="./assets/a1-logo.svg" alt="A1" width="40"> Яндекс Аудитории MCP

[![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)
[![Glama](https://glama.ai/mcp/servers/A1-x-Tech/mcp-yandex-audience/badges/score.svg)](https://glama.ai/mcp/servers/A1-x-Tech/mcp-yandex-audience)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

**A1 Яндекс Аудитории MCP** подключает AI-приложение к сегментам, пикселям и доступам [Яндекс Аудиторий](https://audience.yandex.ru). Попросите на естественном языке показать, что уже есть в аккаунте, подготовить сегмент из 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. Начните с безопасного запроса, например: «Покажи мои сегменты в Яндекс Аудиториях: названия, типы и текущие статусы».

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

**Через интерфейс приложения:**

1. Откройте **Settings → MCP servers**.
2. Нажмите **Add server**.
3. Выберите **STDIO**, затем укажите команду запуска `npx -y mcp-yandex-audience@latest`.

4. Нажмите **Save**, затем **Restart**.

**Через командную строку:**

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

Проверьте подключение:

```bash
codex mcp list
```

Затем в чате Codex попросите: «Подключи Яндекс Аудитории».

[Официальная инструкция Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)

</details>

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

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

Проверьте подключение:

```bash
claude mcp list
```

Затем начните диалог с просьбы подключить Яндекс Аудитории.

[Официальная инструкция Claude Code](https://code.claude.com/docs/en/mcp)

</details>

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

Актуальный официальный путь — **Settings → Extensions**. Для пользовательского desktop extension откройте **Advanced settings → Extension Developer → Install Extension…**, выберите файл `.mcpb` и следуйте подсказкам.

Этот репозиторий сейчас публикует npm-пакет со stdio и пока не содержит `.mcpb`. Поэтому используйте приведённый ниже JSON stdio-конфиг как fallback только в сборках Claude Desktop, где ещё поддерживается локальная конфигурация:

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

В таких сборках сохраните его в `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\Claude\claude_desktop_config.json` на Windows.

После сохранения откройте новый диалог и попросите подключить Яндекс Аудитории.

[Официальная инструкция Claude Desktop](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)

</details>

<details>
<summary>Cursor</summary>

Пользовательский локальный сервер добавляется в Cursor через файл `mcp.json`:

- macOS и Linux: `~/.cursor/mcp.json`
- Windows: `%USERPROFILE%\.cursor\mcp.json`

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

В чате Cursor сервер появится среди доступных инструментов. Попросите подключить Яндекс Аудитории и пройдите вход через Яндекс.

[Официальная инструкция Cursor](https://cursor.com/docs/mcp)

</details>

Откройте палитру команд и выполните **MCP: Open User Configuration**. VS Code создаст пользовательский файл MCP. Добавьте в него:

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

Проверьте запуск командой **MCP: List Servers**, затем откройте чат и попросите подключить Яндекс Аудитории.

[Официальная инструкция VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)

</details>

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

### Проверить, что уже есть в аккаунте

- Посмотреть сегменты, их типы, статусы и идентификаторы.
- Найти сегменты, которые ещё обрабатываются, завершились ошибкой или содержат недостаточно данных.
- Посмотреть пиксели, их охваты за 7, 30 и 90 дней, а также сегменты, созданные на их основе.
- Узнать, кому выдан доступ к конкретному сегменту.

### Подготовить сегмент из CRM

- Загрузить CSV с колонками `email`, `phone`, `ext_id` или `external_id`.
- Загрузить TSV/TXT с идентификаторами устройств, MAC-адресами или SHA256-хешами.
- Проверить параметры загруженного сегмента перед подтверждением.
- Сохранить сегмент с нужным именем и типом данных, затем проверить ход обработки.

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

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

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

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

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

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

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

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

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

| Сущность | Что с ней можно делать |
|---|---|
| **Сегмент** | Список со статусами обработки, загрузка из CRM-файла, похожая аудитория, сегмент по пикселю, переименование и удаление. |
| **Пиксель** | Список с охватами за 7, 30 и 90 дней, создание, переименование и удаление. |
| **Доступ** | Кому доступен сегмент; выдача и отзыв прав на просмотр или редактирование. |

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

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

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

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

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

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

| Действие | Что происходит | Изменяет аккаунт |
|---|---|---:|
| Просмотр сегментов, пикселей и доступов | Читает доступные объекты и их состояние | Нет |
| Загрузка файла | Создаёт объект сегмента со статусом `uploaded` | Да |
| Подтверждение сегмента | Сохраняет параметры и запускает обработку | Да |
| Создание похожего или пиксельного сегмента | Создаёт новый сегмент | Да |
| Переименование сегмента или пикселя | Изменяет название существующего объекта | Да |
| Выдача и отзыв доступа | Меняет права пользователя на сегмент | Да |
| Удаление сегмента | Удаляет сегмент без возможности восстановления | Да, необратимо |
| Удаление пикселя | Удаляет пиксель; восстановление возможно отдельным методом API | Да |

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

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

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

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

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

Проверить состояние — попросите «покажи статус подключения к Аудиториям», отключить — «отключи Аудитории». Выданный приложению доступ отзывается в [Яндекс ID](https://id.yandex.ru/security).

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

| Переменная | Назначение |
|---|---|
| `YANDEX_AUDIENCE_TOKEN` | Готовый OAuth-токен; имеет приоритет над подключением из чата. Такой токен сервер не обновляет и не удаляет. |
| `YANDEX_AUDIENCE_OAUTH_CLIENT_ID` | Client ID собственного OAuth-приложения вместо приложения A1-x-Tech; Redirect URI — `https://oauth.yandex.ru/verification_code`. |
| `YANDEX_AUDIENCE_API_HOST` | Хост API; по умолчанию `https://api-audience.yandex.ru`, для международных аккаунтов можно указать `.com`. |
| `YANDEX_AUDIENCE_TIMEOUT_MS` | Таймаут одного запроса; по умолчанию 60 000 мс. |
| `YANDEX_AUDIENCE_MAX_RETRIES` | Число повторов при ограничении API; по умолчанию 3. Для 5xx и сетевых ошибок повторяются только запросы чтения. |
| `ASKADS_TELEMETRY` | `0`, `false`, `off` или `no` отключает анонимную телеметрию. |

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

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) — и передайте его серверу в `YANDEX_AUDIENCE_TOKEN`.

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

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

Сервер запускается на вашей машине и обращается к `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`](./src/telemetry.ts).

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

```bash
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-возможностей](./docs/capabilities/index.md) — страницы по пользовательским задачам для каждого инструмента.
- [Все инструменты](./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/) — официальная документация.

## Поддержка

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

Yandex Audience MCP

About

Details

README

More