mcp-yandex-audience

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

**Яндекс Аудитории 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><strong>Codex</strong></summary>

<br>

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

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

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

```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><strong>Claude Code</strong></summary>

<br>

```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><strong>Claude Desktop</strong></summary>

<br>

1. Откройте Claude Desktop и перейдите в **Settings → Developer**.
2. Нажмите **Edit Config**. Claude откроет файл настроек в текстовом редакторе.
3. Добавьте сервер в `mcpServers`:

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

Если кнопки **Edit Config** нет, откройте файл напрямую:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

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

[Официальная инструкция Claude Desktop](https://claude.com/docs/connectors/building/mcp-apps/getting-started)

</details>

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

<br>

Пользовательский локальный сервер добавляется в 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>

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

<br>

Откройте палитру команд и выполните **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` | Да |
| Подт