vk-ads-mcp

MCP (Model Context Protocol) server for the VK Ads API. Allows AI assistants to manage VK advertising campaigns, ad groups, banners, audiences, and more through a standardized tool interface.

Installation

npx -y vk-ads-mcp

Or install globally:

npm install -g vk-ads-mcp

Configuration

Set the following environment variables:

| Variable | Required | Description | |---|---|---| | VK_ACCESS_TOKEN | Yes | VK Ads API access token | | VK_PROXY_URL | No | API proxy URL (defaults to https://rk.targethunter.ru/vkr.request) |

Claude Desktop

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "vk-ads": {
      "command": "npx",
      "args": ["-y", "vk-ads-mcp"],
      "env": {
        "VK_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Building a campaign (P0 create-flow)

1. vk_upload_image → returns a Content.id
2. vk_get_packages → pick a package_id, read its objective and banner_fields (slot names for content/textblocks/urls); vk_get_banner_fields / vk_get_goals help resolve slots and goals
3. vk_create_ad_plan with nested ad_groups[] (each with package_id) and nested banners[] (three slot maps: content with { id: <Content.id> }, textblocks, urls) — created transactionally in one call. Or build incrementally with vk_create_ad_group + vk_create_banner
4. vk_remoderate_banners to (re)submit for moderation

The API client targets the VK Ads API and selects the endpoint version (v2 / v3) per call, defaulting to v2.

Tools

Account

• vk_get_user -- Get current user/ad account info
• vk_get_throttling -- Get API rate limit info

Ad Plans (Campaigns)

• vk_get_ad_plans -- List campaigns with filtering and pagination
• vk_get_ad_plan -- Get single campaign details by ID
• vk_create_ad_plan -- Create a campaign transactionally with nested ad groups and banners in one call. Requires ad_groups[] (≥1, each with a package_id and optional nested banners[])
• vk_update_ad_plan -- Update a campaign
• vk_delete_ad_plan -- Delete a campaign
• vk_mass_action_ad_plans -- Bulk start/stop/delete campaigns

Ad Groups

• vk_get_ad_groups -- List ad groups with filtering
• vk_get_ad_group -- Get single ad group details
• vk_create_ad_group -- Create an ad group standalone in an existing campaign. Requires ad_plan_id, name and package_id (from vk_get_packages); optional nested banners[]
• vk_update_ad_group -- Update an ad group
• vk_delete_ad_group -- Delete an ad group
• vk_mass_action_ad_groups -- Bulk start/stop/delete ad groups

Banners (Ads)

• vk_get_banners -- List banners with filtering
• vk_get_banner -- Get single banner details
• vk_create_banner -- Create a banner. content / textblocks / urls are three separate slot→value maps; the slot set is defined by the package's BannerFields (vk_get_packages / vk_get_banner_fields). content.<slot>.id = the Content.id returned by vk_upload_image
• vk_update_banner -- Update a banner (same three slot maps)
• vk_remoderate_banners -- Send banners for (re)moderation (moderation_status is read-only and changes only this way)
• vk_delete_banner -- Delete a banner
• vk_mass_action_banners -- Bulk start/stop/delete banners

Statistics

• vk_get_statistics -- Get performance stats (impressions, clicks, spend, CTR) for campaigns, ad groups, or banners by day/hour/summary

Remarketing

• vk_get_remarketing_users_lists -- List remarketing audiences
• vk_get_remarketing_users_list -- Get single audience details
• vk_create_remarketing_users_list -- Create an audience (upload emails, phones, VK IDs)
• vk_delete_remarketing_users_list -- Delete an audience
• vk_get_remarketing_counters -- List remarketing pixels
• vk_get_remarketing_counter -- Get single pixel details
• vk_create_remarketing_counter -- Create a remarketing pixel
• vk_delete_remarketing_counter -- Delete a remarketing pixel

Targeting

• vk_get_regions -- List regions for targeting
• vk_get_interests -- List interest categories for targeting
• vk_get_projection -- Estimate audience size for targeting parameters

Agency

• vk_get_agency_clients -- List agency clients
• vk_get_agency_client -- Get single client details
• vk_get_agency_managers -- List agency managers
• vk_get_agency_manager -- Get single manager details

Media

• vk_upload_image -- Upload a static creative (image) via multipart (content/static.json) from a local file_path or file_base64. Returns a Content object whose id goes into banner.content.<slot>.id

Reference (campaign build inputs)

• vk_get_packages -- List placement packages. Each package carries id (→ package_id), objective, and banner_fields[] (the slot set for content/textblocks/urls). First step of building a campaign
• vk_get_banner_fields -- Get a package's banner field slots by package_id (extracted from packages.json)
• vk_get_goals -- List available goals for priced_goal / autobidding_mode=max_goals

Blacklists

• vk_get_blacklists -- List placement blacklists
• vk_get_blacklist -- Get single blacklist details

License

ISC