Avito Ads MCP

MCP-сервер для API Авито Рекламы (Avito Ads) — рекламного кабинета медийных и performance-кампаний. Спрашивайте Claude, Cursor, Codex или любой другой MCP-клиент о кампаниях, группах объявлений, креативах и их статистике на естественном языке; переводите деньги между субаккаунтами агентства и оформляйте документы ОРД, не открывая веб-кабинет.

Это не API продавца Авито. Авито Реклама — рекламный кабинет: медийные и performance-кампании, которые покупает рекламодатель или агентство. Товарные объявления, переписка с покупателями, заказы и продвижение товаров живут за другим API — его закрывает community-сервер avito-mcp; доступы от него сюда не подходят, и наоборот. Если вы пришли ответить на сообщение покупателя, это не тот репозиторий.

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

1. Получите Client Key и Client Secret в кабинете Авито Рекламы (нужна роль администратора) и запишите id рекламного аккаунта.

2. Добавьте сервер — например, в Claude Code (другие клиенты):

   claude mcp add avito-ads \
     -e AVITO_ADS_CLIENT_ID=your_client_key \
     -e AVITO_ADS_CLIENT_SECRET=your_client_secret \
     -e AVITO_ADS_ACCOUNT_ID=your_account_id \
     -- npx -y mcp-avito-ads@latest
   

3. Спросите ассистента: «Покажи кампании моего аккаунта Авито и расход за прошлую неделю по группам».

Что умеет

• Рекламные объекты (только чтение) — list_campaigns, list_groups, list_creatives: постраничные списки кампаний, групп объявлений и самих креативов с фильтрами, статусом, бюджетом, ставкой, моделью оплаты, сроками размещения и юридическими данными ОРД.
• Статистика — campaign_stats, group_stats, creative_stats: показы, клики, CTR, расход, расход бонусов, CPM, CPC и квартили видео / VTR — по дням и итогом за период.
• Деньги — change_group_budget и change_group_price: бюджет и ставка одной группы объявлений. Это единственные редактируемые поля во всём дереве рекламных объектов.
• Аккаунт, балансы и субаккаунты агентства — get_account, get_balance, list_child_accounts, list_child_accounts_with_balances, create_child_account, transfer_funds, transfer_bonus.
• Документы ОРД — create_advertiser, list_advertisers, create_contract, list_contracts: записи о рекламодателе и договоре, без которых по закону о маркировке рекламы кампанию не запустить.
• Доступы к аккаунту — list_users, add_user, set_user_role, delete_user.
• Универсальный raw_request — прямой вызов любого пути API, для эндпоинтов без отдельного инструмента.

Полный справочник: docs/TOOLS.md — 25 инструментов.

Чего не умеет

API Авито Рекламы намеренно узкий, и никакой MCP-сервер его не расширит:

• Кампании, группы объявлений и креативы нельзя создавать, редактировать, ставить на паузу, возобновлять, архивировать и удалять через API. Это остаётся в веб-кабинете.
• Таргетинги API не отдаёт вообще — ни на чтение, ни на запись.
• Креативы нельзя загрузить и нельзя отправить на модерацию.
• Рекламодатели и договоры — только на добавление: эндпоинтов изменения и удаления нет, поэтому ошибочная запись так и останется в аккаунте.
• Переводы денег необратимы. Нет ни эндпоинта отмены, ни журнала переводов.
• Аккаунт задан переменной AVITO_ADS_ACCOUNT_ID; ни один инструмент не принимает id аккаунта, поэтому модель не уйдёт в чужой (transfer_funds выбирает только получателя).

Недельная квота баллов

Это самая неожиданная в эксплуатации особенность API Авито Рекламы, так что планируйте с оглядкой на неё:

• Каждый вызов тратит баллы из недельного бюджета, а не упирается в лимит запросов в секунду.
• Бюджет пополняется по понедельникам в 00:00 UTC. Истратили его во вторник — до следующего понедельника аккаунт фактически ничего не прочитает.
• В каждом ответе приходит заголовок Api-Point-Balance, и сервер прокидывает его в каждый результат инструмента как apiPointBalance (null, если API заголовок не прислал). Ассистент видит остаток с каждым ответом и может распределять запросы сам.

Практические следствия, о которых стоит предупредить ассистента:

• Лучше один широкий период статистики, чем много узких: ограничение в 100 дней на запрос существует ровно затем, чтобы длинный отчёт был одним вызовом.
• limit лучше ставить до 100, а не обходить страницы по 20.
• Проверки на стороне клиента (даты, суммы, правила договоров, границы страниц) выполняются до запроса, поэтому некорректный вызов не стоит баллов.
• При HTTP 429 в самой ошибке приходят Retry-After (как его прислал сервер) и остаток баллов, с которым вызов не прошёл, — так ассистент знает, когда можно вернуться.

Примеры

• «Сколько кампания 4242 потратила в прошлом месяце в разбивке по группам объявлений?»
• «У каких дочерних аккаунтов кончились деньги?»
• «Подними ставку группы объявлений 101 до 350 рублей.»
• «Покажи креативы, не прошедшие модерацию.»
• «Зарегистрируй рекламодателя с ИНН 7707083893 и договор оказания услуг для него.»

Установка

claude mcp add avito-ads \
  -e AVITO_ADS_CLIENT_ID=your_client_key \
  -e AVITO_ADS_CLIENT_SECRET=your_client_secret \
  -e AVITO_ADS_ACCOUNT_ID=your_account_id \
  -- npx -y mcp-avito-ads@latest

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "servers": {
    "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"
      }
    }
  }
}

Получение доступа

1. Откройте кабинет Авито Рекламы под пользователем с ролью администратора рекламного аккаунта — пользователь с ролью viewer доступы к API выдать не может.
2. Создайте там приложение API и скопируйте его Client Key и Client Secret. Это пара для OAuth2 client_credentials, которую сервер меняет на Bearer-токен по адресу https://api.avito.ru/token.
3. Запишите id рекламного аккаунта, которому принадлежат доступы, — к нему привязан каждый путь API (v1/account/{accountID}/...).
4. Пропишите их в AVITO_ADS_CLIENT_ID, AVITO_ADS_CLIENT_SECRET и AVITO_ADS_ACCOUNT_ID.

⚠️ Секрет хранится в конфиге MCP-клиента открытым текстом — относитесь к нему как к паролю. У дочерних аккаунтов агентства, созданных через create_child_account, свои собственные clientKey / clientSecret: они возвращаются один раз и потом уже не читаются.

Песочница

Задайте AVITO_ADS_ENVIRONMENT=sandbox — и сервер пойдёт на https://api.avito.ru/ads-sandbox/ вместо https://api.avito.ru/ads/. Так можно отрепетировать инструменты записи, не трогая настоящие деньги. Тестовый аккаунт заводит create_sandbox_account — вне AVITO_ADS_ENVIRONMENT=sandbox сервер этот инструмент не выполняет, — и запущенный сервер не подхватывает возвращённый id: чтобы работать с этим аккаунтом, пропишите id в AVITO_ADS_ACCOUNT_ID.

Три вещи, которые стоит знать до того, как потратите эту единственную попытку, — ни одной из них нет в официальной документации:

• Один аккаунт на ключ. На второй create_sandbox_account приходит 403 нельзя создать второй аккаунт в песочнице.
• Тестовые данные генерируются один раз, в момент создания, и только если у аккаунта уже есть действующий договор. Без договора аккаунт создаётся с предупреждением и остаётся пустым — ни кампаний, ни групп, ни статистики, — а регистрация договора задним числом их не добавит.
• Песочница — не полная копия боевого API: get_balance отвечает там 404.

Квоты считаются по окружениям: у продакшена и песочницы свой недельный баланс баллов.

Настройка

Имена переменных совпадают с официальным Avito Ads SDK, так что один набор доступов работает и там, и здесь.

Требования

• Node.js 20+ (запускается через npx, отдельная установка не нужна).
• Аккаунт Авито Рекламы с доступами к API — см. Получение доступа.

Безопасность

• Записи размечены по смыслу через аннотации MCP-инструментов: чтения — readOnlyHint, смена бюджета, ставки и роли — идемпотентные записи, создание — неидемпотентные, а переводы денег и delete_user помечены как разрушительные (destructive): клиенты, которые спрашивают подтверждение, спросят именно про них.
• raw_request требует явного confirmWrite: true для POST и DELETE, отклоняет любой путь, выходящий за корень API (защита от SSRF), — так Bearer-токен не уйдёт на чужой хост, — и отклоняет любой путь к аккаунту, отличному от AVITO_ADS_ACCOUNT_ID, — в том числе такой, который пытается добраться до него через ...
• Записи никогда не повторяются после сетевой ошибки или 5xx: повторный перевод средств отправил бы деньги дважды. Чтения повторяются с нарастающей паузой.

Документация

• Все инструменты — полный справочник с параметрами и ответами.
• Разработка — сборка, тесты, smoke-проверка, телеметрия.
• Публикация — релиз и размещение в каталоге MCP.

Смотрите также

• Ask Ads — чат-аналитик и «Сторож» рекламных кабинетов от авторов этого сервера: алерты о сливах бюджета и поломках трекинга — в Telegram.
• Avito Ads SDK для TypeScript — официальный SDK; этот сервер независимо реализует тот же протокол обмена.

Поддержка

Вопросы, идеи и доработки — пишите в Telegram: @gistrec.

Лицензия

MIT — см. LICENSE.