VK Ads MCP
MCP server for VK Ads (VK Реклама) API: manage ad plans, ad groups, banners, and statistics.
Open source Open in the app JSON README (API)
About
MCP server for VK Ads (VK Реклама) API: manage ad plans, ad groups, banners, and statistics.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- askads
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.4.1
- Stars
- 5
- Last push
- 2026-08-21T15:30:13Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:27
- Updated
- 2026-08-29 03:02:27
- Origin id
io.github.askads/mcp-vk-ads
README
# VK Реклама MCP
[](https://www.npmjs.com/package/mcp-vk-ads)
[](https://github.com/askads/mcp-vk-ads/actions/workflows/ci.yml)
[](https://glama.ai/mcp/servers/askads/mcp-vk-ads)
[](./LICENSE)
**VK Реклама MCP** подключает AI-приложение к рекламному кабинету VK Ads. Можно спросить, какие кампании тратят бюджет без результата, сравнить группы и объявления, подготовить новую кампанию или изменить ставку. В отличие от ручного перехода по разделам кабинета, ассистент сопоставляет кампании, статистику, баланс и статусы в одном диалоге.
- **18 инструментов.** Кампании, группы, объявления, статистика, баланс, лимиты API, регионы и универсальный запрос к API.
- **Живая реклама.** Ставки, бюджеты и расход отображаются в валюте рекламного кабинета — без пересчёта микроединиц.
- **Полная иерархия.** Кампания (`ad_plan`) → группа (`ad_group`) → объявление (`banner`).
- **Сначала анализ.** Списки, отчёты, баланс и статусы доступны только на чтение.
- **Изменения — в боевом кабинете.** Создание, обновление и действия со статусами применяются сразу; у VK Ads нет песочницы.
Начните с безопасного запроса:
> Покажи кампании моего аккаунта VK Рекламы и расход за прошлую неделю по группам объявлений.
[Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация)
---
## Увидеть работу за минуту
<img src="docs/demo.gif" alt="Демонстрация: ассистент сопоставляет кампании, статистику и баланс VK Рекламы" width="1000">
## Содержание
- [Быстрый старт](#быстрый-старт)
- [Что можно поручить](#что-можно-поручить)
- [Как устроены объекты VK Рекламы](#как-устроены-объекты-vk-рекламы)
- [Что может изменить данные](#что-может-изменить-данные)
- [Как получить токен](#как-получить-токен)
- [Настройка](#настройка)
- [Данные, лимиты и работа в фоне](#данные-лимиты-и-работа-в-фоне)
- [Техническая документация](#техническая-документация)
- [Поддержка](#поддержка)
## Быстрый старт
Нужны Node.js 20 или новее и access-токен VK Ads. Сервер запускается через `npx`, поэтому отдельно устанавливать пакет не требуется.
1. [Получите токен](#как-получить-токен) и добавьте сервер в AI-приложение — инструкции для пяти приложений ниже.
2. Спросите: «Покажи кампании моего аккаунта VK Рекламы и расход за прошлую неделю по группам объявлений».
<details open>
<summary><strong>Codex</strong></summary>
<br>
**Через интерфейс приложения:**
1. Откройте **Settings → Plugins → MCP servers**.
2. Нажмите **Add server**.
3. Добавьте команду запуска `npx -y mcp-vk-ads@latest` и переменную окружения `VK_ADS_TOKEN` со своим токеном.
**Через командную строку:**
```bash
codex mcp add vk-ads \
--env VK_ADS_TOKEN=ваш_токен \
-- npx -y mcp-vk-ads@latest
```
Проверьте подключение:
```bash
codex mcp list
```
[Официальная инструкция Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
</details>
<details>
<summary><strong>Claude Code</strong></summary>
<br>
```bash
claude mcp add \
--env VK_ADS_TOKEN=ваш_токен \
--transport stdio \
--scope user \
vk-ads \
-- npx -y mcp-vk-ads@latest
```
Проверьте сервер:
```bash
claude mcp list
```
[Документация Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp)
</details>
<details>
<summary><strong>Claude Desktop</strong></summary>
<br>
Откройте **Settings → Developer → Edit Config** и добавьте сервер в `claude_desktop_config.json`:
```json
{
"mcpServers": {
"vk-ads": {
"command": "npx",
"args": ["-y", "mcp-vk-ads@latest"],
"env": {
"VK_ADS_TOKEN": "ваш_токен"
}
}
}
}
```
Если **Edit Config** недоступна, отредактируйте `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\Claude\claude_desktop_config.json` на Windows.
</details>
<details>
<summary><strong>Cursor</strong></summary>
<br>
Для всех проектов создайте `~/.cursor/mcp.json`; только для текущего проекта — `.cursor/mcp.json`:
```json
{
"mcpServers": {
"vk-ads": {
"command": "npx",
"args": ["-y", "mcp-vk-ads@latest"],
"env": {
"VK_ADS_TOKEN": "ваш_токен"
}
}
}
}
```
[Документация Cursor](https://docs.cursor.com/context/model-context-protocol)
</details>
<details>
<summary><strong>VS Code</strong></summary>
<br>
Откройте палитру команд и выполните **MCP: Open User Configuration**. Добавьте в `mcp.json`:
```json
{
"servers": {
"vk-ads": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-vk-ads@latest"],
"env": {
"VK_ADS_TOKEN": "${input:vk_ads_token}"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "vk_ads_token",
"description": "Access-токен VK Ads",
"password": true
}
]
}
```
Проверьте запуск командой **MCP: List Servers**.
[Документация VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
</details>
## Что можно поручить
### Разобраться с расходом и результатом
- «Покажи расход, показы, клики и CTR по кампаниям за последние 7 дней».
- «Какие объявления тратят больше всего и не приносят результата?»
- «Сравни группы объявлений внутри этой кампании по расходу и кликам».
### Понять, почему реклама не показывается
- «Покажи статус, доставку и модерацию всех объявлений этой группы».
- «Какие кампании сейчас остановлены?»
- «Найди объявления, которые не прошли модерацию».
### Подготовить изменения в рекламе
- «Создай текстовую кампанию с дневным бюджетом 5 000 рублей».
- «Измени дневной бюджет этой группы на 1 500 рублей».
- «Останови объявление 12345».
Такие команды меняют боевой кабинет. Перед вызовом убедитесь, что ассистент правильно определил кампанию, группу, объявление и сумму.
### Найти данные для настройки
- «Покажи баланс и валюту моего кабинета».
- «Сколько запросов к API осталось?»
- «Найди ID региона Москва для таргетинга».
## Как устроены объекты VK Рекламы
| Объект | Роль |
|---|---|
| **Кампания (`ad_plan`)** | Верхний уровень: название, бюджет, ставка и период работы. |
| **Группа (`ad_group`)** | Настройки аудитории и размещения, собственные бюджет и ставка. |
| **Объявление (`banner`)** | Тексты, ссылки и креатив внутри группы. |
| **Статистика** | Отчёт по кампаниям, группам или объявлениям за период. |
У объекта есть три разных состояния. `status` можно менять: `active`, `blocked` или `deleted`. `delivery` и `moderation_status` только объясняют, почему объект показывается или нет; напрямую их изменить нельзя.
## Что может изменить данные
| Действие | Что происходит |
|---|---|
| Списки, статистика, баланс, лимиты и регионы | Только чтение. |
| Создание и обновление кампаний, групп и объявлений | Сразу создаёт или меняет объект в боевом рекламном кабинете. |
| Действие со статусом | Активирует, останавливает или удаляет объект в живом кабинете. |
| `raw_request` | `GET` читает данные; `POST` и `DELETE` меняют их и требуют `confirmWrite=true`. |
У типизированных инструментов создания, обновления и смены статуса нет внутреннего параметра `confirmWrite`. Как AI-приложение запрашивает подтверждение, зависит от его настроек. После сетевой ошибки или `5xx` не повторяйте создание вслепую: операция могла успеть примениться, сначала проверьте список объектов.
## Как получить токен
Токен выдаёт кабинет VK Ads:
1. В [ads.vk.com](https://ads.vk.com) откройте **Настройки → Доступ к API** и создайте приложение. Сохраните `client_id` и `client_secret`. Если раздел недоступен, запросите доступ к API у поддержки VK Ads.
2. Обменяйте их на access-токен кабинета:
```bash
curl -X POST https://ads.vk.com/api/v2/oauth2/token.json \
-d grant_type=client_credentials \
-d client_id=ВАШ_CLIENT_ID \
-d client_secret=ВАШ_CLIENT_SECRET
```
3. Возьмите `access_token` из ответа и сохраните его как `VK_ADS_TOKEN`.
Токен даёт доступ к рекламному кабинету, включая возможность тратить бюджет, и хранится в конфигурации MCP-клиента открытым текстом. Относитесь к нему как к паролю. Если API отвечает `invalid_token`, выпустите и укажите новый токен.
Для агентств, работающих с кабинетами клиентов, нужен сценарий `authorization_code` — см. [документацию VK Ads API](https://ads.vk.com/doc/api).
## Настройка
| Переменная | Назначение |
|---|---|
| `VK_ADS_TOKEN` | Обязательный OAuth2 access-токен VK Ads. |
| `VK_ADS_LANG` | Язык ответов API; по умолчанию `ru`. |
| `VK_ADS_TIMEOUT_MS` | Таймаут одного запроса; по умолчанию 60 000 мс. |
| `VK_ADS_MAX_RETRIES` | Число повторов при временных ошибках; по умолчанию 3. |
| `VK_ADS_API_BASE` | Базовый адрес API; по умолчанию `https://ads.vk.com/api`. |
## Данные, лимиты и работа в фоне
- **Страницы и большие кабинеты.** Одна страница списка содержит до 250 объектов. При `autoPaginate` сервер возвращает не более 1 000 объектов и помечает неполный результат полем `_truncated`.
- **Лимиты API.** Инструмент `get_throttling` показывает текущий остаток лимитов. Проверяйте его перед массовыми операциями.
- **Повторы запросов.** Таймаут одного запроса — 60 секунд. Сервер делает до трёх повторов: для любого метода при `429`, а для чтения ещё при сетевой ошибке, тайм-ауте и `5xx`. Задержка учитывает `Retry-After` и не превышает 30 секунд.
- **Нет фонового наблюдения.** Сервер работает, когда его вызывает AI-приложение. Если приложение поддерживает задания по расписанию, в нём можно настроить периодический запрос статистики или статусов.
- **Анонимная телеметрия.** По умолчанию сервер отправляет случайный идентификатор установки, имя события или инструмента, версии сервера, Node.js, ОС и AI-клиента. В неё не попадают токен, данные кабинета, аргументы инструментов, ваши сообщения и значения переменных окружения. Отключить её для MCP-серверов Ask Ads: `ASKADS_TELEMETRY=0`.
## Техническая документация
- [Каталог MCP-возможностей](./docs/capabilities/index.md) — страницы по пользовательским задачам для каждого инструмента.
- [Все инструменты и параметры](./docs/TOOLS.md)
- [Документация по разработке](./docs/DEVELOPMENT.md)
- [Пакет в npm](https://www.npmjs.com/package/mcp-vk-ads)
- [Документация VK Ads API](https://ads.vk.com/doc/api)
## Поддержка
Нашли ошибку или не хватает сценария? [Создайте issue](https://github.com/askads/mcp-vk-ads/issues) или напишите в [Telegram](http://t.me/gistrec).