Avito Ads MCP
MCP server for the Avito Ads API: campaigns, ad groups, creatives, statistics and balances.
Open source Open in the app JSON README (API)
About
MCP server for the Avito Ads API: campaigns, ad groups, creatives, statistics and balances.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- a1-x-tech
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.1.0
- Last push
- 2026-08-30T13:36:08Z
- 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-avito-ads
README
# <img src="./assets/a1-logo.svg" alt="A1" width="40"> Авито Реклама MCP
[](https://www.npmjs.com/package/mcp-avito-ads)
[](https://github.com/A1-x-Tech/mcp-avito-ads/actions/workflows/ci.yml)
[](https://glama.ai/mcp/servers/A1-x-Tech/mcp-avito-ads)
[](./LICENSE)
**A1 Авито Реклама MCP** подключает AI-приложение к рекламному кабинету Авито Рекламы. Он помогает проверить кампании и статистику, управлять бюджетом и ставкой группы, работать с балансами агентства, доступами и документами ОРД — на естественном языке.
Это не API продавца Авито: сервер не работает с товарами, перепиской, заказами или продвижением объявлений продавца. Он работает только с медийными и performance-кампаниями рекламного кабинета Авито Рекламы.
- **25 инструментов.** Кампании, группы, креативы, статистика, баланс, дочерние аккаунты, пользователи и документы ОРД.
- **Узкие изменения кампаний.** API позволяет менять только бюджет и ставку группы; создавать, редактировать, ставить на паузу или удалять кампании, группы и креативы нельзя.
- **Необратимые операции видны.** Перевод денег или бонусов, удаление пользователя и технический запрос API помечены как destructive.
- **Недельный бюджет API.** Каждый вызов тратит баллы; остаток `apiPointBalance` сервер возвращает с результатом.
Начните с запроса, который только читает данные:
> Покажи кампании моего аккаунта Авито и расход за прошлую неделю по группам объявлений.
[Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация)
---
## Увидеть работу за минуту
> **Вы:** Покажи кампании моего аккаунта Авито и расход за прошлую неделю по группам объявлений.
>
> **Ассистент:** Показывает кампании, группы, расход, клики и показы. Ничего не меняется.
>
> **Вы:** Подготовь изменение ставки группы 101 до 350 рублей.
>
> **Ассистент:** Показывает аккаунт, группу, текущую и новую ставку, затем запрашивает подтверждение.
>
> **Вы:** Подтверждаю.
>
> **Ассистент:** Меняет ставку только этой группы. Кампания, креативы и другие группы не меняются.
## Содержание
- [Быстрый старт](#быстрый-старт)
- [Что можно поручить](#что-можно-поручить)
- [Что может измениться](#что-может-измениться)
- [Получение доступа](#получение-доступа)
- [Настройка](#настройка)
- [Данные, лимиты и работа в фоне](#данные-лимиты-и-работа-в-фоне)
- [Техническая документация](#техническая-документация)
- [Поддержка](#поддержка)
## Быстрый старт
Нужны Node.js 20+, Client Key, Client Secret и ID рекламного аккаунта Авито Рекламы. Для выдачи доступов нужна роль администратора аккаунта.
1. [Получите доступ](#получение-доступа).
2. Добавьте сервер в AI-приложение.
3. Отправьте безопасный первый запрос выше.
<details open><summary><strong>Codex</strong></summary>
<br>
В **Settings → MCP servers** нажмите **Add server**, выберите **STDIO**, укажите команду `npx -y mcp-avito-ads@latest` и переменные окружения `AVITO_ADS_CLIENT_ID`, `AVITO_ADS_CLIENT_SECRET` и `AVITO_ADS_ACCOUNT_ID`, затем нажмите **Save**, потом **Restart**.
```bash
codex mcp add avito-ads \
--env AVITO_ADS_CLIENT_ID=your_client_key \
--env AVITO_ADS_CLIENT_SECRET=your_client_secret \
--env AVITO_ADS_ACCOUNT_ID=your_account_id \
-- npx -y mcp-avito-ads@latest
codex mcp list
```
[Документация Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
</details>
<details><summary><strong>Claude Code</strong></summary>
<br>
```bash
claude mcp add \
--env AVITO_ADS_CLIENT_ID=your_client_key \
--env AVITO_ADS_CLIENT_SECRET=your_client_secret \
--env AVITO_ADS_ACCOUNT_ID=your_account_id \
--transport stdio --scope user avito-ads \
-- npx -y mcp-avito-ads@latest
claude mcp list
```
[Документация Claude Code MCP](https://code.claude.com/docs/en/mcp)
</details>
<details><summary><strong>Claude Desktop</strong></summary>
<br>
Актуальный официальный путь — **Settings → Extensions**. Для пользовательского desktop extension откройте **Advanced settings → Extension Developer → Install Extension…**, выберите файл `.mcpb` и следуйте подсказкам.
Этот репозиторий сейчас публикует npm-пакет со stdio и пока не содержит `.mcpb`. Поэтому используйте приведённый ниже JSON stdio-конфиг как fallback только в сборках Claude Desktop, где ещё поддерживается локальная конфигурация:
```json
{"mcpServers":{"avito-ads":{"command":"npx","args":["-y","mcp-avito-ads@latest"],"env":{"AVITO_ADS_CLIENT_ID":"your_client_key","AVITO_ADS_CLIENT_SECRET":"your_client_secret","AVITO_ADS_ACCOUNT_ID":"your_account_id"}}}}
```
В таких сборках сохраните его в `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\Claude\claude_desktop_config.json` на Windows.
[Документация Claude Desktop MCP](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
</details>
<details><summary><strong>Cursor</strong></summary>
<br>
Добавьте `{"mcpServers":{"avito-ads":{"type":"stdio","command":"npx","args":["-y","mcp-avito-ads@latest"],"env":{"AVITO_ADS_CLIENT_ID":"your_client_key","AVITO_ADS_CLIENT_SECRET":"your_client_secret","AVITO_ADS_ACCOUNT_ID":"your_account_id"}}}}` в `~/.cursor/mcp.json` на macOS/Linux или `%USERPROFILE%\.cursor\mcp.json` на Windows. [Документация Cursor MCP](https://cursor.com/docs/mcp)
</details>
<details><summary><strong>VS Code</strong></summary>
<br>
Запустите **MCP: Open User Configuration** и добавьте:
```json
{"servers":{"avito-ads":{"type":"stdio","command":"npx","args":["-y","mcp-avito-ads@latest"],"env":{"AVITO_ADS_CLIENT_ID":"${input:avito_client_id}","AVITO_ADS_CLIENT_SECRET":"${input:avito_client_secret}","AVITO_ADS_ACCOUNT_ID":"${input:avito_account_id}"}}},"inputs":[{"type":"promptString","id":"avito_client_id","description":"Avito Ads Client Key"},{"type":"promptString","id":"avito_client_secret","description":"Avito Ads Client Secret","password":true},{"type":"promptString","id":"avito_account_id","description":"ID рекламного аккаунта"}]}
```
Проверьте сервер командой **MCP: List Servers**. [Документация VS Code MCP](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
</details>
## Что можно поручить
- Покажи кампании, группы, креативы, статусы и статистику за период.
- Сравни расход, CTR, CPM, CPC или VTR по группам и креативам.
- Проверь баланс и дочерние аккаунты агентства.
- Подготовь изменение бюджета или ставки одной группы.
- Создай рекламодателя и договор ОРД, сначала показав передаваемые реквизиты.
- Добавь пользователя, измени его роль или отзови доступ после подтверждения.
## Что может измениться
| Операция | Что происходит | Граница подтверждения |
|---|---|---|
| Кампании, группы, креативы, статистика, баланс, пользователи и ОРД | Читает данные аккаунта | Ничего не меняет |
| Бюджет или ставка группы | Меняет одно из двух доступных API-полей группы | Меняет рекламную группу |
| Пользователь и роль | Выдаёт доступ или меняет роль | Меняет доступы аккаунта |
| Рекламодатель, договор, дочерний или sandbox-аккаунт | Создаёт новую запись | Необратимо создаёт объект |
| Перевод денег или бонусов, удаление пользователя | Меняет баланс или удаляет доступ | Разрушительно и необратимо |
| Raw API request | Может менять данные при `confirmWrite: true` | Потенциально разрушительно |
Кампании, группы и креативы нельзя создавать, редактировать, ставить на паузу, архивировать или удалять через этот API. Креативы и таргетинги тоже недоступны для записи.
## Получение доступа
1. Откройте кабинет Авито Рекламы пользователем с ролью администратора.
2. Создайте API-приложение и скопируйте **Client Key** и **Client Secret**.
3. Скопируйте ID рекламного аккаунта.
4. Передайте их как `AVITO_ADS_CLIENT_ID`, `AVITO_ADS_CLIENT_SECRET`, `AVITO_ADS_ACCOUNT_ID`.
Сервер получает Bearer token через OAuth2 `client_credentials`. Храните Client Secret как пароль. ID аккаунта задан конфигурацией: инструменты не смогут случайно перейти в другой аккаунт.
Для репетиции записей можно задать `AVITO_ADS_ENVIRONMENT=sandbox`. Песочница не является полной копией production: например, баланс там недоступен.
## Настройка
| Переменная | Обязательна | Описание |
|---|---|---|
| `AVITO_ADS_CLIENT_ID` | Да | Client Key API-приложения. |
| `AVITO_ADS_CLIENT_SECRET` | Да | Client Secret API-приложения. |
| `AVITO_ADS_ACCOUNT_ID` | Да | ID рекламного аккаунта. |
| `AVITO_ADS_ENVIRONMENT` | Нет | `production` или `sandbox`; по умолчанию `production`. |
| `AVITO_ADS_TIMEOUT_MS` | Нет | Тайм-аут запроса; по умолчанию `30000` мс. |
| `AVITO_ADS_MAX_RETRIES` | Нет | Повторы 429; по умолчанию `4`. |
## Данные, лимиты и работа в фоне
- **Недельный бюджет баллов.** Баллы пополняются в понедельник в 00:00 UTC. Один длинный отчёт до 100 дней обычно экономнее серии коротких; сервер показывает `apiPointBalance` с каждым результатом.
- **Временные ошибки.** При 429 в ошибке возвращаются `Retry-After` и остаток баллов. Записи не повторяются после сетевой или 5xx ошибки, чтобы не перевести деньги дважды.
- **Постоянного наблюдения нет.** Сервер работает только при вызове. Если AI-приложение поддерживает задания по расписанию, оно может периодически собирать статистику и остаток баллов.
- **Анонимная телеметрия.** В неё не попадают секреты, данные аккаунта, аргументы и промпты; отключение: `ASKADS_TELEMETRY=0`.
## Техническая документация
- [Каталог MCP-возможностей](./docs/capabilities/index.md) — страницы по пользовательским задачам для каждого инструмента.
- [Все инструменты и параметры](./docs/TOOLS.md)
- [Документация по разработке](./docs/DEVELOPMENT.md)
- [Документация по публикации](./docs/PUBLISHING.md)
- [Официальный Avito Ads SDK](https://github.com/avito-tech/avito-ads-sdk-typescript)
## Поддержка
Нашли ошибку или не хватает сценария? [Создайте issue](https://github.com/A1-x-Tech/mcp-avito-ads/issues) или напишите в [Telegram](https://t.me/a1_mcp).
<br>
<p align="center">
<img src="https://github.com/ztemerbekov/a1-yandex-kit-skills/raw/main/assets/images/mona-hifive-yandex-kit-warm.gif" alt="Две Моны дают пять" width="256">
</p>
<p align="center">
Вы дочитали до конца!
</p>