vk-ads-mcp
This server provides an MCP interface for the VK Ads API, enabling management of campaigns, ad groups, ads, statistics, and account information.
List Campaigns: Retrieve advertising campaigns with optional filtering by status (active, blocked, deleted), with automatic pagination.
Create Campaign: Create a new campaign by specifying a name, objective/type, and budget limits.
Update Campaign: Modify an existing campaign's name, budget, or status (activate, stop, delete).
List Ad Groups: Get a list of ad groups with targeting information, filterable by campaign.
List Ads: Retrieve individual ads filterable by campaign or ad group, including format and status details.
Create Ad: Create a new ad by defining the format (text, image, video), title, description, link URL, and associated ad group.
Get Statistics: Fetch performance metrics (impressions, clicks, spend) for campaigns or ads over a date range, aggregated by day, week, month, or as an overall summary.
List Targeting Groups: Retrieve targeting groups associated with a specific campaign.
Get Account / Budget: Retrieve account information, current balance, and budget limits.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vk-ads-mcp Покажи статистику по кампании за последнюю неделю"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
VK Ads MCP — управление рекламой ВКонтакте через нейросеть
Если вы искали, как подключить рекламный кабинет VK Ads к ИИ-ассистенту, спрашивать про открутку и остаток бюджета обычными словами или собирать отчёты по кампаниям без выгрузок в Excel — это оно. 8 инструментов поверх VK Ads API v2 (ads.vk.com/api/v2): кампании, группы объявлений, объявления, статистика и баланс.
Модель данных VK Ads:
ad_plans(кампании) →ad_groups(группы) →banners(объявления). Имена инструментов оставлены дружелюбными (list_campaigns,list_ads), но обращаются к реальным v2-ресурсам.
Установка
Claude Desktop
{
"mcpServers": {
"vk-ads": {
"command": "npx",
"args": ["-y", "@theyahia/vk-ads-mcp"],
"env": {
"VK_ADS_TOKEN": "ваш_токен"
}
}
}
}Claude Code
claude mcp add vk-ads -e VK_ADS_TOKEN=ваш_токен -- npx -y @theyahia/vk-ads-mcpRelated MCP server: Meta Ads MCP Server
Авторизация
Переменная | Обязательна | Назначение |
| ✅ | OAuth2 Bearer access_token VK Ads API |
| — | для авто-обновления токена (refresh) |
| — | для авто-обновления токена (refresh) |
| — | для авто-обновления токена (refresh) |
access_token живёт ~1 день. Если заданы все три refresh-переменные, сервер на 401 сам обновит токен
через grant_type=refresh_token. Иначе — обновляйте VK_ADS_TOKEN вручную.
Кабинет выбирается токеном, а не параметром. В VK Ads v2 нет account_id в запросах: агентство/менеджер
получает отдельный per-client токен (agency_client_credentials) и подписывает им запросы нужного кабинета.
Инструменты (8)
Инструмент | Метод | Описание |
|
| Кампании (ad_plans), фильтр по статусу, авто-пагинация |
|
| Создать кампанию: |
|
| Обновить: |
|
| Группы объявлений с таргетингом (delivery), фильтр по кампаниям |
|
| Объявления (banners), фильтр по группам, авто-пагинация |
|
| Создать объявление: |
|
| Показы ( |
|
| Кабинет и баланс (нужен scope |
Все инструменты используют MCP-аннотации (readOnlyHint/destructiveHint/idempotentHint), а read-инструменты —
outputSchema + structuredContent для типизированного и компактного ответа. Списки пагинируются автоматически
(до 200 объектов; больше — флаг truncated в ответе).
Примеры запросов
Покажи активные кампании
Создай кампанию "Осенняя акция" с целью traffic и бюджетом 50000
Останови кампанию 12345
Какие группы объявлений в кампании 12345?
Статистика кампании 12345 за январь 2026 по дням
Покажи баланс кабинетаМиграция 1.x → 2.0 (breaking)
Версия 1.x обращалась к легаси API (/campaigns.json, /ads.json, плоский /statistics.json, account_id,
числовые статусы) и фактически не работала против ads.vk.com/api/v2. В 2.0 переписан весь API-слой:
account_idудалён из всех инструментов — кабинет задаётся токеном.update_campaign: вместоstatus: 1/0→action: activate|stop|delete(строковые статусыactive/blocked/deleted).Бюджет:
all_limit→budget_limit/budget_limit_day(валюта кабинета, не копейки).create_campaign:type→objective(цель кампании).create_ad: вместо{ad_format,title,description,link_url}→{ad_group_id, textblocks, urls, content}.get_statistics:ids_type/period=week|month|overall→object_typeиperiod=day|summaryв пути URL.list_targeting_groups→list_ad_groups(таргетинг живёт на группе объявлений).get_budget→get_account(баланс читается из/user.json).
Точность API
Эндпоинты и поля подтверждены официальной документацией target.vk.ru и 5 независимыми рабочими клиентами.
Несколько деталей помечены в коде // VERIFY: (единицы бюджета, поле баланса, полный enum objective, путь update)
и требуют подтверждения живым токеном — см. docs/VERIFICATION.md (~10 минут).
Возможный follow-up (вне текущего объёма)
Массовые действия (mass_action), список клиентов агентства (agency/clients), загрузка креативов
(upload_creative), состояние лимитов (throttling), справочники таргетинга (regions/interests),
конверсии и remarketing-аудитории.
Разработка
npm install
npm run build # tsc
npm test # vitest
npm run dev # tsx src/index.ts (читает .env — см. .env.example)Лицензия
MIT
Telegram: @vhodvai
Available Tools
8 toolscreate_adB
Создать объявление VK Ads: формат, заголовок, описание, ссылка.
Inputs: campaign_id (required), ad_group_id, format, title, +2 more.
create_campaignB
Создать рекламную кампанию VK Ads: название, тип, бюджет.
Inputs: account_id (required), name (required), type, budget.
get_budgetB
Бюджет рекламного кабинета VK Ads: остаток, лимиты.
Inputs: account_id (required).
get_statisticsA
Статистика VK Ads: показы, клики, расход за период по кампаниям/объявлениям.
Inputs: account_id (required), ids (required), date_from (required), date_to (required), +2 more.
list_adsC
Объявления VK Ads по кампаниям: формат, статус, данные.
Inputs: campaign_ids (required).
list_campaignsA
Список рекламных кампаний VK Ads по кабинету с фильтрацией по статусу.
Inputs: account_id (required), status.
list_targeting_groupsC
Группы таргетинга кампании VK Ads.
Inputs: campaign_id (required).
update_campaignB
Обновить кампанию VK Ads: название, бюджет, статус (start/stop).
Inputs: campaign_id (required), name, budget, status.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct action and resource (ad, campaign, budget, statistics, targeting groups), with no ambiguity between them.
All tool names follow a consistent verb_noun snake_case pattern (e.g., create_ad, list_campaigns), making them predictable and easy to understand.
8 tools is well-scoped for managing VK Ads, covering creation, listing, updates, statistics, and budget without being excessive or insufficient.
Missing delete operations for both ads and campaigns, no update for ads, and no individual get endpoints, which leaves notable gaps in lifecycle coverage.
Maintenance
Related MCP Connectors
Meta Ads MCP server: run Facebook and Instagram campaigns, ad sets, ads and reports from AI.
Google Ads MCP server — manage campaigns, keywords, and metrics.
Reddit Ads MCP server: run Reddit campaigns, ad groups, ads and reports from AI.
Google Ads MCP server: run Search, Display, Demand Gen and PMax campaigns from AI.
Related MCP Servers
- AlicenseAqualityDmaintenanceRead-only MCP server for analyzing VK Ads campaigns, listing ad structures, retrieving statistics, and generating optimization recommendations.81MIT
- AlicenseNot gradedqualityDmaintenancePython MCP server that exposes Meta Marketing API data, providing tools to manage ad accounts, campaigns, and analytics through natural language interfaces.MIT
- AlicenseAqualityBmaintenanceMCP server for VK Ads API: manage ad plans, ad groups, banners, and statistics.23196 npm13MIT
- AlicenseNot gradedqualityAmaintenanceMCP server for VK Ads API (myTarget v2) that allows AI agents to manage advertising accounts: create and modify campaigns, ads, upload creatives, and fetch statistics.145 npm6Apache 2.0