vk-ads-mcp
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 list my ad plans"
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
Hardened fork of lexamarketolog/vk-ads-mcp. Управляет рекламными кампаниями в VK Реклама (myTarget API v2) через любой MCP-клиент — Claude Code, Claude Desktop, Cursor и другие. По умолчанию работает только на чтение; мутирующие операции включаются явно через VK_ADS_ENABLE_WRITES=true. Каждый партнёр использует собственные API-ключи.
Возможности
Чтение (24 инструмента, всегда доступны)
Позволяют просматривать данные аккаунта, не изменяя ничего в кабинете.
auth_check, get_account_info,
list_ad_plans, get_ad_plan,
list_campaigns, get_campaign,
list_ad_groups, get_ad_group,
list_banners, get_banner,
get_statistics_day, get_statistics_summary, get_statistics_breakdown, get_async_report,
list_remarketing_groups, list_remarketing_pixels, get_lookalike,
list_users_lists,
list_content,
list_feeds,
list_agency_clients,
list_packages, search_regions, get_dictionary
Управление (31 инструмент, только при VK_ADS_ENABLE_WRITES=true)
Мутирующие операции — создание, изменение, удаление объектов, загрузка файлов. Требуют явного включения, так как затрагивают бюджет и данные кампаний.
create_ad_plan, update_ad_plan, delete_ad_plan,
create_campaign, update_campaign, set_campaign_status, delete_campaign,
create_ad_group, update_ad_group, delete_ad_group,
create_banner, update_banner, moderate_banner, delete_banner,
upload_image, upload_video,
create_remarketing_group, update_remarketing_group, delete_remarketing_group,
create_remarketing_pixel, delete_remarketing_pixel,
create_lookalike,
create_users_list, upload_users_list_items, delete_users_list,
create_feed, update_feed, delete_feed,
create_agency_client,
create_async_report,
revoke_token
Related MCP server: meta-ads-mcp
Терминология VK Ads API (важно)
API использует устаревшие имена myTarget. В новом кабинете ads.vk.com:
Интерфейс кабинета | Имя в API | MCP-инструменты |
Кампания (верхний уровень) |
|
|
Группа объявлений |
|
|
Объявление |
|
|
Внимание:
campaignбезad_plan_idсоздаётся без ошибки, но становится «сиротой» и не отображается в новом кабинете. Всегда привязывайте кампанию к плану.
Установка
Claude Code
claude mcp add vk-ads \
--env VK_ADS_CLIENT_ID=<id> \
--env VK_ADS_CLIENT_SECRET=<secret> \
-- uvx --from git+https://github.com/nikolaymokh-dev/vk-ads-mcp@v0.1.0 vk-ads-mcp.claude.json / Cursor / другие MCP-клиенты
{
"mcpServers": {
"vk-ads": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/nikolaymokh-dev/vk-ads-mcp@v0.1.0",
"vk-ads-mcp"
],
"env": {
"VK_ADS_CLIENT_ID": "<id>",
"VK_ADS_CLIENT_SECRET": "<secret>"
}
}
}
}Вместо client_id/client_secret можно передать готовый токен:
"env": {
"VK_ADS_ACCESS_TOKEN": "<token>"
}Включение управления кампаниями
Добавьте переменную окружения VK_ADS_ENABLE_WRITES=true при запуске сервера:
claude mcp add vk-ads \
--env VK_ADS_CLIENT_ID=<id> \
--env VK_ADS_CLIENT_SECRET=<secret> \
--env VK_ADS_ENABLE_WRITES=true \
-- uvx --from git+https://github.com/nikolaymokh-dev/vk-ads-mcp@v0.1.0 vk-ads-mcpИли в JSON-конфиге:
"env": {
"VK_ADS_CLIENT_ID": "<id>",
"VK_ADS_CLIENT_SECRET": "<secret>",
"VK_ADS_ENABLE_WRITES": "true"
}Внимание: мутирующие инструменты могут создавать объекты, менять статусы и тратить рекламный бюджет. Включайте только там, где это действительно нужно.
Настройка доступа
Как получить API-ключи в кабинете VK Реклама: docs/SETUP.md.
Безопасность
Что защищает этот форк и какие ограничения остаются: docs/SECURITY.md.
Отличия от оригинала (что добавил форк)
Этот форк добавляет слой безопасности поверх lexamarketolog/vk-ads-mcp, не меняя поведение самих инструментов:
Read-only по умолчанию — 31 мутирующий инструмент скрыт, пока не задан
VK_ADS_ENABLE_WRITES=true.Защита upload от SSRF — блок непубличных адресов (loopback/RFC1918/link-local
169.254.169.254/CGNAT) +follow_redirects=False.Запрет чтения произвольных файлов — локальный upload только из
VK_ADS_ALLOW_LOCAL_UPLOAD=<dir>(с проверкой path-traversal).Lock
base_urlнаads.vk.com(override черезVK_ADS_ALLOW_BASE_URL_OVERRIDE).Защита от path-traversal в пользовательских значениях, попадающих в URL-путь.
Воспроизводимая установка через
uvxпо тегу, запинённыйuv.lock, CI, тесты безопасности.
Полный список — в CHANGELOG.md; модель угроз — в docs/SECURITY.md.
Лицензия
MIT — форк lexamarketolog/vk-ads-mcp, см. NOTICE.
Available Tools
24 toolsauth_checkA
Verify credentials and API reachability.
Returns current user info if token is valid, otherwise an error payload.
Inputs: no named parameters. Returns: object
get_account_infoA
Get current account info (including balance/budget fields).
Inputs: no named parameters. Returns: object
get_ad_groupC
Get a single ad group by ID.
Inputs: ad_group_id (required), fields. Returns: object
get_ad_planB
Get a single ad plan by ID.
Inputs: ad_plan_id (required), fields. Returns: object
get_async_reportC
Get async report status or download link when ready.
Inputs: report_id (required). Returns: object
get_bannerB
Get a single banner by ID.
Inputs: banner_id (required), fields. Returns: object
get_campaignC
Get a single campaign by ID.
Inputs: campaign_id (required), fields. Returns: object
get_dictionaryA
Fetch an arbitrary VK Ads dictionary.
Examples:
name="interests"→/api/v2/interests.jsonname="browsers"→/api/v2/browsers.jsonname="currencies"→/api/v2/currencies.jsonname="sectors"→/api/v2/sectors.json
Inputs: name (required), params. Returns: object
get_lookalikeB
Get a lookalike audience (incl. processing status).
Inputs: lookalike_id (required). Returns: object
get_statistics_breakdownC
Statistics sliced by a dimension.
Args:
entity: campaigns | ad_groups | banners.
ids: comma-separated IDs.
group_by: one of age, gender, region, placement, os, device_type.
metrics: metric group.
Inputs: entity (required), ids (required), date_from (required), date_to (required), +2 more. Returns: object
get_statistics_dayB
Daily statistics.
Args:
entity: one of campaigns, ad_groups, banners, users.
ids: comma-separated entity IDs (e.g. "123,456").
date_from: YYYY-MM-DD.
date_to: YYYY-MM-DD.
metrics: optional metric group (e.g. base, video, uniques, all).
Inputs: entity (required), ids (required), date_from (required), date_to (required), +1 more. Returns: object
get_statistics_summaryC
Summary (aggregated) statistics for the period.
Args mirror get_statistics_day.
Inputs: entity (required), ids (required), date_from, date_to, +1 more. Returns: object
list_ad_groupsB
List ad groups, optionally filtered by campaign_id.
Inputs: campaign_id, limit, offset, fields. Returns: object
list_ad_plansC
List ad plans (top-level entity visible as "Кампания" in VK Ads UI).
Inputs: limit, offset, fields. Returns: object
list_agency_clientsC
List clients managed under an agency account.
Inputs: limit, offset. Returns: object
list_bannersC
List banners (individual ads).
Inputs: campaign_id, ad_group_id, limit, offset, +1 more. Returns: object
list_campaignsA
List advertising campaigns.
Args: limit: max items (default 50, max 250). offset: pagination offset. status: filter by status (active, blocked, deleted, etc.). fields: comma-separated field list to return.
Inputs: limit, offset, status, fields. Returns: object
list_contentB
List uploaded content.
Args:
content_type: one of static, video, html5.
limit, offset: pagination.
Inputs: content_type, limit, offset. Returns: object
list_feedsC
List product feeds for dynamic/shopping ads.
Inputs: limit, offset. Returns: object
list_packagesA
List available ad packages (ad formats / placements).
Inputs: no named parameters. Returns: object
list_remarketing_groupsC
List remarketing audiences.
Inputs: limit, offset. Returns: object
list_remarketing_pixelsC
List remarketing pixels (tracking tags).
Inputs: limit, offset. Returns: object
list_users_listsB
List custom-audience users lists (uploaded phone/email hash segments).
Inputs: limit, offset. Returns: object
search_regionsC
Search geo regions for targeting (cities, regions).
Inputs: query (required), limit. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Each tool targets a distinct entity or action (authentication, specific entities like campaign/ad group, statistics variants, different list operations). No two tools overlap in function; get/list pairs are complementary. The three statistics tools are differentiated by aggregation level (breakdown, daily, summary).
All tool names follow a consistent snake_case pattern with clear verb prefixes: 'get_' for single entities, 'list_' for plural entities, 'search_' for search, 'auth_' for authentication. No mixing of conventions or unclear verbs.
24 tools cover a broad range of VK Ads operations (auth, account, campaigns, ad groups, banners, ads, statistics, dictionaries, remarketing, content, feeds, packages, regions). The count is well-scoped for a comprehensive ads management server, neither too sparse nor bloated.
The tool surface is entirely read-only: only get, list, search, and statistics tools exist. There are no create, update, or delete operations for any entity (campaigns, ad groups, banners, etc.), which severely limits practical use for campaign management. Critical mutation capabilities are missing.
Maintenance
Related MCP Connectors
Read-only MCP access to your DEXUN AdWhiz account: ad accounts, AI recommendations, savings.
Meta Ads MCP: Facebook and Instagram reports, campaigns, creatives, audiences. Approval on writes.
Managed Amazon Seller Central and Ads access for OAuth-capable MCP clients.
Meta Ads MCP: read ad accounts and signal health; propose governed changes under Ask or Full.
Related MCP Servers
- AlicenseAqualityDmaintenanceRead-only MCP server for analyzing VK Ads campaigns, listing ad structures, retrieving statistics, and generating optimization recommendations.81MIT
- FlicenseNot gradedqualityCmaintenanceEnables read-only Meta Ads reporting and diagnostics, plus safe, preview-before-apply mutations such as campaign creation, duplication, targeting replacement, and attribution changes.-
- AlicenseAqualityCmaintenanceEnables MCP clients such as Claude to read Google Ads performance reports, run keyword planner queries, and create or manage search and Performance Max campaigns, ad groups, keywords, ads, budgets, and delivery status. Write operations default to paused and can be disabled entirely for read-only analytics use.16MIT
- AlicenseBqualityBmaintenanceEnables MCP clients to read Snapchat Ads campaigns and performance and to prepare preview-first changes for selected ad accounts, with opt-in write tools and explicit confirmation before applying updates.21131 npmApache 2.0