{
  "markdown": "# VK Реклама MCP\n\n[![npm](https://img.shields.io/npm/v/mcp-vk-ads)](https://www.npmjs.com/package/mcp-vk-ads)\n[![CI](https://github.com/askads/mcp-vk-ads/actions/workflows/ci.yml/badge.svg)](https://github.com/askads/mcp-vk-ads/actions/workflows/ci.yml)\n[![Glama](https://glama.ai/mcp/servers/askads/mcp-vk-ads/badges/score.svg)](https://glama.ai/mcp/servers/askads/mcp-vk-ads)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\n**VK Реклама MCP** подключает AI-приложение к рекламному кабинету VK Ads. Можно спросить, какие кампании тратят бюджет без результата, сравнить группы и объявления, подготовить новую кампанию или изменить ставку. В отличие от ручного перехода по разделам кабинета, ассистент сопоставляет кампании, статистику, баланс и статусы в одном диалоге.\n\n- **18 инструментов.** Кампании, группы, объявления, статистика, баланс, лимиты API, регионы и универсальный запрос к API.\n- **Живая реклама.** Ставки, бюджеты и расход отображаются в валюте рекламного кабинета — без пересчёта микроединиц.\n- **Полная иерархия.** Кампания (`ad_plan`) → группа (`ad_group`) → объявление (`banner`).\n- **Сначала анализ.** Списки, отчёты, баланс и статусы доступны только на чтение.\n- **Изменения — в боевом кабинете.** Создание, обновление и действия со статусами применяются сразу; у VK Ads нет песочницы.\n\nНачните с безопасного запроса:\n\n> Покажи кампании моего аккаунта VK Рекламы и расход за прошлую неделю по группам объявлений.\n\n[Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация)\n\n---\n\n## Увидеть работу за минуту\n\n<img src=\"docs/demo.gif\" alt=\"Демонстрация: ассистент сопоставляет кампании, статистику и баланс VK Рекламы\" width=\"1000\">\n\n## Содержание\n\n- [Быстрый старт](#быстрый-старт)\n- [Что можно поручить](#что-можно-поручить)\n- [Как устроены объекты VK Рекламы](#как-устроены-объекты-vk-рекламы)\n- [Что может изменить данные](#что-может-изменить-данные)\n- [Как получить токен](#как-получить-токен)\n- [Настройка](#настройка)\n- [Данные, лимиты и работа в фоне](#данные-лимиты-и-работа-в-фоне)\n- [Техническая документация](#техническая-документация)\n- [Поддержка](#поддержка)\n\n## Быстрый старт\n\nНужны Node.js 20 или новее и access-токен VK Ads. Сервер запускается через `npx`, поэтому отдельно устанавливать пакет не требуется.\n\n1. [Получите токен](#как-получить-токен) и добавьте сервер в AI-приложение — инструкции для пяти приложений ниже.\n2. Спросите: «Покажи кампании моего аккаунта VK Рекламы и расход за прошлую неделю по группам объявлений».\n\n<details open>\n<summary><strong>Codex</strong></summary>\n\n<br>\n\n**Через интерфейс приложения:**\n\n1. Откройте **Settings → Plugins → MCP servers**.\n2. Нажмите **Add server**.\n3. Добавьте команду запуска `npx -y mcp-vk-ads@latest` и переменную окружения `VK_ADS_TOKEN` со своим токеном.\n\n**Через командную строку:**\n\n```bash\ncodex mcp add vk-ads \\\n  --env VK_ADS_TOKEN=ваш_токен \\\n  -- npx -y mcp-vk-ads@latest\n```\n\nПроверьте подключение:\n\n```bash\ncodex mcp list\n```\n\n[Официальная инструкция Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)\n\n</details>\n\n<details>\n<summary><strong>Claude Code</strong></summary>\n\n<br>\n\n```bash\nclaude mcp add \\\n  --env VK_ADS_TOKEN=ваш_токен \\\n  --transport stdio \\\n  --scope user \\\n  vk-ads \\\n  -- npx -y mcp-vk-ads@latest\n```\n\nПроверьте сервер:\n\n```bash\nclaude mcp list\n```\n\n[Документация Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp)\n\n</details>\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\n<br>\n\nОткройте **Settings → Developer → Edit Config** и добавьте сервер в `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"vk-ads\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-vk-ads@latest\"],\n      \"env\": {\n        \"VK_ADS_TOKEN\": \"ваш_токен\"\n      }\n    }\n  }\n}\n```\n\nЕсли **Edit Config** недоступна, отредактируйте `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\\Claude\\claude_desktop_config.json` на Windows.\n\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\n<br>\n\nДля всех проектов создайте `~/.cursor/mcp.json`; только для текущего проекта — `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"vk-ads\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-vk-ads@latest\"],\n      \"env\": {\n        \"VK_ADS_TOKEN\": \"ваш_токен\"\n      }\n    }\n  }\n}\n```\n\n[Документация Cursor](https://docs.cursor.com/context/model-context-protocol)\n\n</details>\n\n<details>\n<summary><strong>VS Code</strong></summary>\n\n<br>\n\nОткройте палитру команд и выполните **MCP: Open User Configuration**. Добавьте в `mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"vk-ads\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-vk-ads@latest\"],\n      \"env\": {\n        \"VK_ADS_TOKEN\": \"${input:vk_ads_token}\"\n      }\n    }\n  },\n  \"inputs\": [\n    {\n      \"type\": \"promptString\",\n      \"id\": \"vk_ads_token\",\n      \"description\": \"Access-токен VK Ads\",\n      \"password\": true\n    }\n  ]\n}\n```\n\nПроверьте запуск командой **MCP: List Servers**.\n\n[Документация VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)\n\n</details>\n\n## Что можно поручить\n\n### Разобраться с расходом и результатом\n\n- «Покажи расход, показы, клики и CTR по кампаниям за последние 7 дней».\n- «Какие объявления тратят больше всего и не приносят результата?»\n- «Сравни группы объявлений внутри этой кампании по расходу и кликам».\n\n### Понять, почему реклама не показывается\n\n- «Покажи статус, доставку и модерацию всех объявлений этой группы».\n- «Какие кампании сейчас остановлены?»\n- «Найди объявления, которые не прошли модерацию».\n\n### Подготовить изменения в рекламе\n\n- «Создай текстовую кампанию с дневным бюджетом 5 000 рублей».\n- «Измени дневной бюджет этой группы на 1 500 рублей».\n- «Останови объявление 12345».\n\nТакие команды меняют боевой кабинет. Перед вызовом убедитесь, что ассистент правильно определил кампанию, группу, объявление и сумму.\n\n### Найти данные для настройки\n\n- «Покажи баланс и валюту моего кабинета».\n- «Сколько запросов к API осталось?»\n- «Найди ID региона Москва для таргетинга».\n\n## Как устроены объекты VK Рекламы\n\n| Объект | Роль |\n|---|---|\n| **Кампания (`ad_plan`)** | Верхний уровень: название, бюджет, ставка и период работы. |\n| **Группа (`ad_group`)** | Настройки аудитории и размещения, собственные бюджет и ставка. |\n| **Объявление (`banner`)** | Тексты, ссылки и креатив внутри группы. |\n| **Статистика** | Отчёт по кампаниям, группам или объявлениям за период. |\n\nУ объекта есть три разных состояния. `status` можно менять: `active`, `blocked` или `deleted`. `delivery` и `moderation_status` только объясняют, почему объект показывается или нет; напрямую их изменить нельзя.\n\n## Что может изменить данные\n\n| Действие | Что происходит |\n|---|---|\n| Списки, статистика, баланс, лимиты и регионы | Только чтение. |\n| Создание и обновление кампаний, групп и объявлений | Сразу создаёт или меняет объект в боевом рекламном кабинете. |\n| Действие со статусом | Активирует, останавливает или удаляет объект в живом кабинете. |\n| `raw_request` | `GET` читает данные; `POST` и `DELETE` меняют их и требуют `confirmWrite=true`. |\n\nУ типизированных инструментов создания, обновления и смены статуса нет внутреннего параметра `confirmWrite`. Как AI-приложение запрашивает подтверждение, зависит от его настроек. После сетевой ошибки или `5xx` не повторяйте создание вслепую: операция могла успеть примениться, сначала проверьте список объектов.\n\n## Как получить токен\n\nТокен выдаёт кабинет VK Ads:\n\n1. В [ads.vk.com](https://ads.vk.com) откройте **Настройки → Доступ к API** и создайте приложение. Сохраните `client_id` и `client_secret`. Если раздел недоступен, запросите доступ к API у поддержки VK Ads.\n2. Обменяйте их на access-токен кабинета:\n\n   ```bash\n   curl -X POST https://ads.vk.com/api/v2/oauth2/token.json \\\n     -d grant_type=client_credentials \\\n     -d client_id=ВАШ_CLIENT_ID \\\n     -d client_secret=ВАШ_CLIENT_SECRET\n   ```\n\n3. Возьмите `access_token` из ответа и сохраните его как `VK_ADS_TOKEN`.\n\nТокен даёт доступ к рекламному кабинету, включая возможность тратить бюджет, и хранится в конфигурации MCP-клиента открытым текстом. Относитесь к нему как к паролю. Если API отвечает `invalid_token`, выпустите и укажите новый токен.\n\nДля агентств, работающих с кабинетами клиентов, нужен сценарий `authorization_code` — см. [документацию VK Ads API](https://ads.vk.com/doc/api).\n\n## Настройка\n\n| Переменная | Назначение |\n|---|---|\n| `VK_ADS_TOKEN` | Обязательный OAuth2 access-токен VK Ads. |\n| `VK_ADS_LANG` | Язык ответов API; по умолчанию `ru`. |\n| `VK_ADS_TIMEOUT_MS` | Таймаут одного запроса; по умолчанию 60 000 мс. |\n| `VK_ADS_MAX_RETRIES` | Число повторов при временных ошибках; по умолчанию 3. |\n| `VK_ADS_API_BASE` | Базовый адрес API; по умолчанию `https://ads.vk.com/api`. |\n\n## Данные, лимиты и работа в фоне\n\n- **Страницы и большие кабинеты.** Одна страница списка содержит до 250 объектов. При `autoPaginate` сервер возвращает не более 1 000 объектов и помечает неполный результат полем `_truncated`.\n- **Лимиты API.** Инструмент `get_throttling` показывает текущий остаток лимитов. Проверяйте его перед массовыми операциями.\n- **Повторы запросов.** Таймаут одного запроса — 60 секунд. Сервер делает до трёх повторов: для любого метода при `429`, а для чтения ещё при сетевой ошибке, тайм-ауте и `5xx`. Задержка учитывает `Retry-After` и не превышает 30 секунд.\n- **Нет фонового наблюдения.** Сервер работает, когда его вызывает AI-приложение. Если приложение поддерживает задания по расписанию, в нём можно настроить периодический запрос статистики или статусов.\n- **Анонимная телеметрия.** По умолчанию сервер отправляет случайный идентификатор установки, имя события или инструмента, версии сервера, Node.js, ОС и AI-клиента. В неё не попадают токен, данные кабинета, аргументы инструментов, ваши сообщения и значения переменных окружения. Отключить её для MCP-серверов Ask Ads: `ASKADS_TELEMETRY=0`.\n\n## Техническая документация\n\n- [Каталог MCP-возможностей](./docs/capabilities/index.md) — страницы по пользовательским задачам для каждого инструмента.\n- [Все инструменты и параметры](./docs/TOOLS.md)\n- [Документация по разработке](./docs/DEVELOPMENT.md)\n- [Пакет в npm](https://www.npmjs.com/package/mcp-vk-ads)\n- [Документация VK Ads API](https://ads.vk.com/doc/api)\n\n## Поддержка\n\nНашли ошибку или не хватает сценария? [Создайте issue](https://github.com/askads/mcp-vk-ads/issues) или напишите в [Telegram](http://t.me/gistrec).\n",
  "bytes": 10527,
  "sha": "9f2ffb768df6b040e8f861536ef832648834f4e8d1e441e2d61c710198d0a9b5",
  "repo_slug": "askads/mcp-vk-ads",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_askads_mcp_vk_ads_973a440f/readme"
}