mcp-avito-ads
Máy chủ MCP cho API Avito Ads (Avito Reklama) — chiến dịch, nhóm quảng cáo, quảng cáo sáng tạo, thống kê, số dư, hợp đồng và quản lý tài khoản cho các tác nhân AI.
Tài liệu
Авито Реклама MCP
A1 Авито Реклама MCP подключает AI-приложение к рекламному кабинету Авито Рекламы. Он помогает проверить кампании и статистику, управлять бюджетом и ставкой группы, работать с балансами агентства, доступами и документами ОРД — на естественном языке.
Это не API продавца Авито: сервер не работает с товарами, перепиской, заказами или продвижением объявлений продавца. Он работает только с медийными и performance-кампаниями рекламного кабинета Авито Рекламы.
- 25 инструментов. Кампании, группы, креативы, статистика, баланс, дочерние аккаунты, пользователи и документы ОРД.
- Узкие изменения кампаний. API позволяет менять только бюджет и ставку группы; создавать, редактировать, ставить на паузу или удалять кампании, группы и креативы нельзя.
- Необратимые операции видны. Перевод денег или бонусов, удаление пользователя и технический запрос API помечены как destructive.
- Недельный бюджет API. Каждый вызов тратит баллы; остаток
apiPointBalanceсервер возвращает с результатом.
Начните с запроса, который только читает данные:
Покажи кампании моего аккаунта Авито и расход за прошлую неделю по группам объявлений.
Подключить сервер · Посмотреть сценарии · Открыть техническую документацию
Увидеть работу за минуту
Вы: Покажи кампании моего аккаунта Авито и расход за прошлую неделю по группам объявлений.
Ассистент: Показывает кампании, группы, расход, клики и показы. Ничего не меняется.
Вы: Подготовь изменение ставки группы 101 до 350 рублей.
Ассистент: Показывает аккаунт, группу, текущую и новую ставку, затем запрашивает подтверждение.
Вы: Подтверждаю.
Ассистент: Меняет ставку только этой группы. Кампания, креативы и другие группы не меняются.
Содержание
- Быстрый старт
- Что можно поручить
- Что может измениться
- Получение доступа
- Настройка
- Данные, лимиты и работа в фоне
- Техническая документация
- Поддержка
Быстрый старт
Нужны Node.js 20+, Client Key, Client Secret и ID рекламного аккаунта Авито Рекламы. Для выдачи доступов нужна роль администратора аккаунта.
- Получите доступ.
- Добавьте сервер в AI-приложение.
- Отправьте безопасный первый запрос выше.
Codex
В 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.
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
Claude Code
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 Desktop
Актуальный официальный путь — Settings → Extensions. Для пользовательского desktop extension откройте Advanced settings → Extension Developer → Install Extension…, выберите файл .mcpb и следуйте подсказкам.
Этот репозиторий сейчас публикует npm-пакет со stdio и пока не содержит .mcpb. Поэтому используйте приведённый ниже JSON stdio-конфиг как fallback только в сборках Claude Desktop, где ещё поддерживается локальная конфигурация:
{"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.
Cursor
Добавьте {"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
VS Code
Запустите MCP: Open User Configuration и добавьте:
{"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
Что можно поручить
- Покажи кампании, группы, креативы, статусы и статистику за период.
- Сравни расход, CTR, CPM, CPC или VTR по группам и креативам.
- Проверь баланс и дочерние аккаунты агентства.
- Подготовь изменение бюджета или ставки одной группы.
- Создай рекламодателя и договор ОРД, сначала показав передаваемые реквизиты.
- Добавь пользователя, измени его роль или отзови доступ после подтверждения.
Что может измениться
| Операция | Что происходит | Граница подтверждения |
|---|---|---|
| Кампании, группы, креативы, статистика, баланс, пользователи и ОРД | Читает данные аккаунта | Ничего не меняет |
| Бюджет или ставка группы | Меняет одно из двух доступных API-полей группы | Меняет рекламную группу |
| Пользователь и роль | Выдаёт доступ или меняет роль | Меняет доступы аккаунта |
| Рекламодатель, договор, дочерний или sandbox-аккаунт | Создаёт новую запись | Необратимо создаёт объект |
| Перевод денег или бонусов, удаление пользователя | Меняет баланс или удаляет доступ | Разрушительно и необратимо |
| Raw API request | Может менять данные при confirmWrite: true | Потенциально разрушительно |
Кампании, группы и креативы нельзя создавать, редактировать, ставить на паузу, архивировать или удалять через этот API. Креативы и таргетинги тоже недоступны для записи.
Получение доступа
- Откройте кабинет Авито Рекламы пользователем с ролью администратора.
- Создайте API-приложение и скопируйте Client Key и Client Secret.
- Скопируйте ID рекламного аккаунта.
- Передайте их как
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-приложение поддерживает задания по расписанию, оно может периодически собирать статистику и остаток баллов.
- Анонимная телеметрия. В неё не попадают секреты, данные аккаунта, аргументы и промпты. При вызове инструмента сервер также отправляет его исход, а при ошибке - фрагмент её текста: код и сообщение, в которых e-mail, адреса, токены, числа от 4 цифр и текст в кавычках заменены на «#». Если в тексте ошибки есть значение из запроса, оно тоже может попасть во фрагмент. Отключение:
ASKADS_TELEMETRY=0.
Техническая документация
- Каталог MCP-возможностей — страницы по пользовательским задачам для каждого инструмента.
- Все инструменты и параметры
- Документация по разработке
- Документация по публикации
- Официальный Avito Ads SDK
Поддержка
Нашли ошибку или не хватает сценария? Создайте issue или напишите в Telegram.
Вы дочитали до конца!