vk-ads-mcp 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# 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
+
+```bash
+npx -y vk-ads-mcp
+```
+
+Or install globally:
+
+```bash
+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`:
+
+```json
+{
+  "mcpServers": {
+    "vk-ads": {
+      "command": "npx",
+      "args": ["-y", "vk-ads-mcp"],
+      "env": {
+        "VK_ACCESS_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+## 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 new campaign
+- **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
+- **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
+- **vk_update_banner** -- Update a banner
+- **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 an image for use in banners
+
+### Blacklists
+- **vk_get_blacklists** -- List placement blacklists
+- **vk_get_blacklist** -- Get single blacklist details
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { VkAdsApi } from "./vk-api.js";
+import { registerAdPlanTools } from "./tools/ad-plans.js";
+import { registerAdGroupTools } from "./tools/ad-groups.js";
+import { registerBannerTools } from "./tools/banners.js";
+import { registerStatisticsTools } from "./tools/statistics.js";
+import { registerRemarketingTools } from "./tools/remarketing.js";
+import { registerTargetingTools } from "./tools/targeting.js";
+import { registerAgencyTools } from "./tools/agency.js";
+import { registerAccountTools } from "./tools/account.js";
+import { registerMediaTools } from "./tools/media.js";
+import { registerBlacklistTools } from "./tools/blacklists.js";
+const accessToken = process.env.VK_ACCESS_TOKEN;
+const proxyUrl = process.env.VK_PROXY_URL || "https://rk.targethunter.ru/vkr.request";
+if (!accessToken) {
+    console.error("VK_ACCESS_TOKEN is required. Set it as environment variable.");
+    process.exit(1);
+}
+const api = new VkAdsApi({ accessToken, proxyUrl });
+const server = new McpServer({
+    name: "vk-ads-mcp",
+    version: "2.0.0",
+});
+registerAccountTools(server, api);
+registerAdPlanTools(server, api);
+registerAdGroupTools(server, api);
+registerBannerTools(server, api);
+registerStatisticsTools(server, api);
+registerRemarketingTools(server, api);
+registerTargetingTools(server, api);
+registerAgencyTools(server, api);
+registerMediaTools(server, api);
+registerBlacklistTools(server, api);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Failed to start VK Ads MCP server:", error);
+    process.exit(1);
+});

package/dist/tools/account.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { VkAdsApi } from "../vk-api.js";
+export declare function registerAccountTools(server: McpServer, api: VkAdsApi): void;

package/dist/tools/account.js

@@ -0,0 +1,10 @@
+export function registerAccountTools(server, api) {
+    server.tool("vk_get_user", "Получить информацию о текущем пользователе/рекламном аккаунте.", {}, async () => {
+        const result = await api.get("user.json");
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_get_throttling", "Получить информацию о лимитах запросов к API (rate limits).", {}, async () => {
+        const result = await api.get("throttling.json");
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/ad-groups.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { VkAdsApi } from "../vk-api.js";
+export declare function registerAdGroupTools(server: McpServer, api: VkAdsApi): void;

package/dist/tools/ad-groups.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+export function registerAdGroupTools(server, api) {
+    server.tool("vk_get_ad_groups", "Получить список групп объявлений (ad groups). Поддерживает фильтрацию по кампании и пагинацию.", {
+        fields: z.string().optional().describe("Поля через запятую, например: id,name,status,ad_plan_id"),
+        limit: z.number().optional().describe("Макс. кол-во результатов (по умолчанию 20, макс 50)"),
+        offset: z.number().optional().describe("Смещение для пагинации"),
+        _id__in: z.string().optional().describe("Фильтр по ID через запятую: 123,456"),
+        _ad_plan_id__in: z.string().optional().describe("Фильтр по ID кампании: 123,456"),
+        _status__in: z.string().optional().describe("Фильтр по статусу"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        if (params.limit)
+            query.limit = String(params.limit);
+        if (params.offset)
+            query.offset = String(params.offset);
+        if (params._id__in)
+            query._id__in = params._id__in;
+        if (params._ad_plan_id__in)
+            query._ad_plan_id__in = params._ad_plan_id__in;
+        if (params._status__in)
+            query._status__in = params._status__in;
+        const result = await api.get("ad_groups.json", query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_get_ad_group", "Получить детали одной группы объявлений по ID.", {
+        id: z.number().describe("ID группы объявлений"),
+        fields: z.string().optional().describe("Поля через запятую"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        const result = await api.get(`ad_groups/${params.id}.json`, query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_create_ad_group", "Создать группу объявлений (ad group) в кампании.", {
+        ad_plan_id: z.number().describe("ID кампании (ad plan), к которой привязать группу"),
+        name: z.string().optional().describe("Название группы"),
+        targeting: z.string().optional().describe("JSON с параметрами таргетинга"),
+        age_restrictions: z.string().optional().describe("Возрастные ограничения"),
+        utm: z.string().optional().describe("UTM-метки"),
+        budget_limit: z.string().optional().describe("Лимит бюджета"),
+        budget_limit_day: z.string().optional().describe("Дневной лимит"),
+        bid_type: z.string().optional().describe("Тип ставки"),
+        max_price: z.string().optional().describe("Максимальная цена"),
+    }, async (params) => {
+        const body = { ad_plan_id: params.ad_plan_id };
+        if (params.name)
+            body.name = params.name;
+        if (params.targeting)
+            body.targeting = JSON.parse(params.targeting);
+        if (params.age_restrictions)
+            body.age_restrictions = params.age_restrictions;
+        if (params.utm)
+            body.utm = params.utm;
+        if (params.budget_limit)
+            body.budget_limit = params.budget_limit;
+        if (params.budget_limit_day)
+            body.budget_limit_day = params.budget_limit_day;
+        if (params.bid_type)
+            body.bid_type = params.bid_type;
+        if (params.max_price)
+            body.max_price = params.max_price;
+        const result = await api.post("ad_groups.json", body);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_update_ad_group", "Обновить группу объявлений.", {
+        id: z.number().describe("ID группы объявлений"),
+        name: z.string().optional().describe("Новое название"),
+        status: z.string().optional().describe("Новый статус"),
+        targeting: z.string().optional().describe("JSON с параметрами таргетинга"),
+        utm: z.string().optional().describe("UTM-метки"),
+        budget_limit: z.string().optional().describe("Лимит бюджета"),
+        budget_limit_day: z.string().optional().describe("Дневной лимит"),
+        max_price: z.string().optional().describe("Максимальная цена"),
+    }, async (params) => {
+        const body = {};
+        if (params.name)
+            body.name = params.name;
+        if (params.status)
+            body.status = params.status;
+        if (params.targeting)
+            body.targeting = JSON.parse(params.targeting);
+        if (params.utm)
+            body.utm = params.utm;
+        if (params.budget_limit)
+            body.budget_limit = params.budget_limit;
+        if (params.budget_limit_day)
+            body.budget_limit_day = params.budget_limit_day;
+        if (params.max_price)
+            body.max_price = params.max_price;
+        const result = await api.post(`ad_groups/${params.id}.json`, body);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_delete_ad_group", "Удалить группу объявлений.", {
+        id: z.number().describe("ID группы для удаления"),
+    }, async (params) => {
+        const result = await api.delete(`ad_groups/${params.id}.json`);
+        return { content: [{ type: "text", text: JSON.stringify(result ?? { success: true }, null, 2) }] };
+    });
+    server.tool("vk_mass_action_ad_groups", "Массовые действия над группами объявлений (пауза, запуск, удаление).", {
+        action: z.enum(["start", "stop", "delete"]).describe("Действие: start, stop, delete"),
+        ids: z.string().describe("ID групп через запятую: 123,456,789"),
+    }, async (params) => {
+        const body = {
+            action: params.action,
+            ids: params.ids.split(",").map((id) => Number(id.trim())),
+        };
+        const result = await api.post("ad_groups/mass_action.json", body);
+        return { content: [{ type: "text", text: JSON.stringify(result ?? { success: true }, null, 2) }] };
+    });
+}

package/dist/tools/ad-plans.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { VkAdsApi } from "../vk-api.js";
+export declare function registerAdPlanTools(server: McpServer, api: VkAdsApi): void;

package/dist/tools/ad-plans.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+export function registerAdPlanTools(server, api) {
+    server.tool("vk_get_ad_plans", "Получить список рекламных кампаний (ad plans). Поддерживает фильтрацию и пагинацию.", {
+        fields: z.string().optional().describe("Поля через запятую, например: id,name,status"),
+        limit: z.number().optional().describe("Макс. кол-во результатов (по умолчанию 20, макс 50)"),
+        offset: z.number().optional().describe("Смещение для пагинации"),
+        _id__in: z.string().optional().describe("Фильтр по ID через запятую: 123,456"),
+        _status__in: z.string().optional().describe("Фильтр по статусу: active,blocked,deleted"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        if (params.limit)
+            query.limit = String(params.limit);
+        if (params.offset)
+            query.offset = String(params.offset);
+        if (params._id__in)
+            query._id__in = params._id__in;
+        if (params._status__in)
+            query._status__in = params._status__in;
+        const result = await api.get("ad_plans.json", query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_get_ad_plan", "Получить детали одной рекламной кампании по ID.", {
+        id: z.number().describe("ID кампании (ad plan)"),
+        fields: z.string().optional().describe("Поля через запятую"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        const result = await api.get(`ad_plans/${params.id}.json`, query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_create_ad_plan", "Создать новую рекламную кампанию (ad plan).", {
+        name: z.string().describe("Название кампании"),
+        objective: z.string().optional().describe("Цель кампании"),
+        budget_limit: z.string().optional().describe("Лимит бюджета"),
+        budget_limit_day: z.string().optional().describe("Дневной лимит бюджета"),
+        autobidding_mode: z.string().optional().describe("Режим автоматических ставок"),
+        mixing: z.string().optional().describe("Настройки микширования"),
+    }, async (params) => {
+        const body = { name: params.name };
+        if (params.objective)
+            body.objective = params.objective;
+        if (params.budget_limit)
+            body.budget_limit = params.budget_limit;
+        if (params.budget_limit_day)
+            body.budget_limit_day = params.budget_limit_day;
+        if (params.autobidding_mode)
+            body.autobidding_mode = params.autobidding_mode;
+        if (params.mixing)
+            body.mixing = params.mixing;
+        const result = await api.post("ad_plans.json", body);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_update_ad_plan", "Обновить рекламную кампанию (ad plan).", {
+        id: z.number().describe("ID кампании"),
+        name: z.string().optional().describe("Новое название"),
+        status: z.string().optional().describe("Новый статус: active, blocked, deleted"),
+        budget_limit: z.string().optional().describe("Лимит бюджета"),
+        budget_limit_day: z.string().optional().describe("Дневной лимит"),
+        autobidding_mode: z.string().optional().describe("Режим автоставок"),
+    }, async (params) => {
+        const body = {};
+        if (params.name)
+            body.name = params.name;
+        if (params.status)
+            body.status = params.status;
+        if (params.budget_limit)
+            body.budget_limit = params.budget_limit;
+        if (params.budget_limit_day)
+            body.budget_limit_day = params.budget_limit_day;
+        if (params.autobidding_mode)
+            body.autobidding_mode = params.autobidding_mode;
+        const result = await api.post(`ad_plans/${params.id}.json`, body);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_delete_ad_plan", "Удалить рекламную кампанию (ad plan).", {
+        id: z.number().describe("ID кампании для удаления"),
+    }, async (params) => {
+        const result = await api.delete(`ad_plans/${params.id}.json`);
+        return { content: [{ type: "text", text: JSON.stringify(result ?? { success: true }, null, 2) }] };
+    });
+    server.tool("vk_mass_action_ad_plans", "Массовые действия над кампаниями (пауза, запуск, удаление). Принимает JSON с массивом ID и действием.", {
+        action: z.enum(["start", "stop", "delete"]).describe("Действие: start, stop, delete"),
+        ids: z.string().describe("ID кампаний через запятую: 123,456,789"),
+    }, async (params) => {
+        const body = {
+            action: params.action,
+            ids: params.ids.split(",").map((id) => Number(id.trim())),
+        };
+        const result = await api.post("ad_plans/mass_action.json", body);
+        return { content: [{ type: "text", text: JSON.stringify(result ?? { success: true }, null, 2) }] };
+    });
+}

package/dist/tools/agency.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { VkAdsApi } from "../vk-api.js";
+export declare function registerAgencyTools(server: McpServer, api: VkAdsApi): void;

package/dist/tools/agency.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+export function registerAgencyTools(server, api) {
+    server.tool("vk_get_agency_clients", "Получить список клиентов агентского аккаунта.", {
+        fields: z.string().optional().describe("Поля через запятую"),
+        limit: z.number().optional().describe("Макс. кол-во результатов"),
+        offset: z.number().optional().describe("Смещение"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        if (params.limit)
+            query.limit = String(params.limit);
+        if (params.offset)
+            query.offset = String(params.offset);
+        const result = await api.get("agency/clients.json", query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_get_agency_client", "Получить информацию об одном клиенте агентства по ID.", {
+        id: z.number().describe("ID клиента"),
+        fields: z.string().optional().describe("Поля через запятую"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        const result = await api.get(`agency/clients/${params.id}.json`, query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_get_agency_managers", "Получить список менеджеров агентства.", {
+        fields: z.string().optional().describe("Поля через запятую"),
+        limit: z.number().optional().describe("Макс. кол-во результатов"),
+        offset: z.number().optional().describe("Смещение"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        if (params.limit)
+            query.limit = String(params.limit);
+        if (params.offset)
+            query.offset = String(params.offset);
+        const result = await api.get("agency/managers.json", query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_get_agency_manager", "Получить информацию об одном менеджере агентства по ID.", {
+        id: z.number().describe("ID менеджера"),
+        fields: z.string().optional().describe("Поля через запятую"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        const result = await api.get(`agency/managers/${params.id}.json`, query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/banners.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { VkAdsApi } from "../vk-api.js";
+export declare function registerBannerTools(server: McpServer, api: VkAdsApi): void;

package/dist/tools/banners.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+export function registerBannerTools(server, api) {
+    server.tool("vk_get_banners", "Получить список баннеров (объявлений). Поддерживает фильтрацию по кампании, группе и пагинацию.", {
+        fields: z.string().optional().describe("Поля через запятую, например: id,status,ad_group_id,moderation_status"),
+        limit: z.number().optional().describe("Макс. кол-во результатов (по умолчанию 20, макс 50)"),
+        offset: z.number().optional().describe("Смещение для пагинации"),
+        _id__in: z.string().optional().describe("Фильтр по ID через запятую: 123,456"),
+        _ad_group_id__in: z.string().optional().describe("Фильтр по ID группы объявлений: 123,456"),
+        _ad_plan_id__in: z.string().optional().describe("Фильтр по ID кампании: 123,456"),
+        _status__in: z.string().optional().describe("Фильтр по статусу"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        if (params.limit)
+            query.limit = String(params.limit);
+        if (params.offset)
+            query.offset = String(params.offset);
+        if (params._id__in)
+            query._id__in = params._id__in;
+        if (params._ad_group_id__in)
+            query._ad_group_id__in = params._ad_group_id__in;
+        if (params._ad_plan_id__in)
+            query._ad_plan_id__in = params._ad_plan_id__in;
+        if (params._status__in)
+            query._status__in = params._status__in;
+        const result = await api.get("banners.json", query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_get_banner", "Получить детали одного баннера (объявления) по ID.", {
+        id: z.number().describe("ID баннера"),
+        fields: z.string().optional().describe("Поля через запятую"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        const result = await api.get(`banners/${params.id}.json`, query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_create_banner", "Создать баннер (объявление) в группе объявлений.", {
+        ad_group_id: z.number().describe("ID группы объявлений"),
+        content: z.string().describe("JSON с контентом баннера (заголовок, текст, изображение, ссылка и т.д.)"),
+        moderation_status: z.string().optional().describe("Статус модерации"),
+    }, async (params) => {
+        const body = {
+            ad_group_id: params.ad_group_id,
+            content: JSON.parse(params.content),
+        };
+        if (params.moderation_status)
+            body.moderation_status = params.moderation_status;
+        const result = await api.post("banners.json", body);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_update_banner", "Обновить баннер (объявление).", {
+        id: z.number().describe("ID баннера"),
+        content: z.string().optional().describe("JSON с новым контентом баннера"),
+        status: z.string().optional().describe("Новый статус"),
+    }, async (params) => {
+        const body = {};
+        if (params.content)
+            body.content = JSON.parse(params.content);
+        if (params.status)
+            body.status = params.status;
+        const result = await api.post(`banners/${params.id}.json`, body);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_delete_banner", "Удалить баннер (объявление).", {
+        id: z.number().describe("ID баннера для удаления"),
+    }, async (params) => {
+        const result = await api.delete(`banners/${params.id}.json`);
+        return { content: [{ type: "text", text: JSON.stringify(result ?? { success: true }, null, 2) }] };
+    });
+    server.tool("vk_mass_action_banners", "Массовые действия над баннерами (пауза, запуск, удаление).", {
+        action: z.enum(["start", "stop", "delete"]).describe("Действие: start, stop, delete"),
+        ids: z.string().describe("ID баннеров через запятую: 123,456,789"),
+    }, async (params) => {
+        const body = {
+            action: params.action,
+            ids: params.ids.split(",").map((id) => Number(id.trim())),
+        };
+        const result = await api.post("banners/mass_action.json", body);
+        return { content: [{ type: "text", text: JSON.stringify(result ?? { success: true }, null, 2) }] };
+    });
+}

package/dist/tools/blacklists.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { VkAdsApi } from "../vk-api.js";
+export declare function registerBlacklistTools(server: McpServer, api: VkAdsApi): void;

package/dist/tools/blacklists.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export function registerBlacklistTools(server, api) {
+    server.tool("vk_get_blacklists", "Получить список чёрных списков площадок (place black lists).", {
+        limit: z.number().optional().describe("Макс. кол-во результатов"),
+        offset: z.number().optional().describe("Смещение"),
+    }, async (params) => {
+        const query = {};
+        if (params.limit)
+            query.limit = String(params.limit);
+        if (params.offset)
+            query.offset = String(params.offset);
+        const result = await api.get("place_black_lists.json", query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_get_blacklist", "Получить один чёрный список площадок по ID.", {
+        id: z.number().describe("ID чёрного списка"),
+    }, async (params) => {
+        const result = await api.get(`place_black_lists/${params.id}.json`);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/media.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { VkAdsApi } from "../vk-api.js";
+export declare function registerMediaTools(server: McpServer, api: VkAdsApi): void;

package/dist/tools/media.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+export function registerMediaTools(server, api) {
+    server.tool("vk_upload_image", "Загрузить изображение для использования в баннерах. Принимает base64-encoded данные или URL изображения.", {
+        image_url: z.string().optional().describe("URL изображения для загрузки"),
+        width: z.number().optional().describe("Ширина изображения"),
+        height: z.number().optional().describe("Высота изображения"),
+    }, async (params) => {
+        const body = {};
+        if (params.image_url)
+            body.image_url = params.image_url;
+        if (params.width)
+            body.width = params.width;
+        if (params.height)
+            body.height = params.height;
+        const result = await api.post("images.json", body);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/remarketing.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { VkAdsApi } from "../vk-api.js";
+export declare function registerRemarketingTools(server: McpServer, api: VkAdsApi): void;

package/dist/tools/remarketing.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+export function registerRemarketingTools(server, api) {
+    // --- Списки пользователей (аудитории ремаркетинга) ---
+    server.tool("vk_get_remarketing_users_lists", "Получить списки аудиторий ремаркетинга (users lists).", {
+        fields: z.string().optional().describe("Поля через запятую"),
+        limit: z.number().optional().describe("Макс. кол-во результатов"),
+        offset: z.number().optional().describe("Смещение"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        if (params.limit)
+            query.limit = String(params.limit);
+        if (params.offset)
+            query.offset = String(params.offset);
+        const result = await api.get("remarketing/users_lists.json", query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_get_remarketing_users_list", "Получить одну аудиторию ремаркетинга по ID.", {
+        id: z.number().describe("ID аудитории"),
+        fields: z.string().optional().describe("Поля через запятую"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        const result = await api.get(`remarketing/users_lists/${params.id}.json`, query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_create_remarketing_users_list", "Создать аудиторию ремаркетинга. Можно загрузить контакты (emails, телефоны, VK ID).", {
+        name: z.string().describe("Название аудитории"),
+        type: z.string().optional().describe("Тип списка: dmp_id, email, phone, idfa_gaid, vk_id, ok_id, mmr_id"),
+        contacts: z.string().optional().describe("Контакты через перенос строки (emails, телефоны или ID)"),
+    }, async (params) => {
+        const body = { name: params.name };
+        if (params.type)
+            body.type = params.type;
+        if (params.contacts)
+            body.contacts = params.contacts;
+        const result = await api.post("remarketing/users_lists.json", body);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_delete_remarketing_users_list", "Удалить аудиторию ремаркетинга.", {
+        id: z.number().describe("ID аудитории для удаления"),
+    }, async (params) => {
+        const result = await api.delete(`remarketing/users_lists/${params.id}.json`);
+        return { content: [{ type: "text", text: JSON.stringify(result ?? { success: true }, null, 2) }] };
+    });
+    // --- Счётчики (пиксели) ---
+    server.tool("vk_get_remarketing_counters", "Получить список счётчиков ремаркетинга (пикселей).", {
+        fields: z.string().optional().describe("Поля через запятую"),
+        limit: z.number().optional().describe("Макс. кол-во результатов"),
+        offset: z.number().optional().describe("Смещение"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        if (params.limit)
+            query.limit = String(params.limit);
+        if (params.offset)
+            query.offset = String(params.offset);
+        const result = await api.get("remarketing/counters.json", query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_get_remarketing_counter", "Получить один счётчик ремаркетинга по ID.", {
+        id: z.number().describe("ID счётчика"),
+        fields: z.string().optional().describe("Поля через запятую"),
+    }, async (params) => {
+        const query = {};
+        if (params.fields)
+            query.fields = params.fields;
+        const result = await api.get(`remarketing/counters/${params.id}.json`, query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_create_remarketing_counter", "Создать счётчик ремаркетинга (пиксель).", {
+        name: z.string().describe("Название счётчика"),
+        domain: z.string().optional().describe("Домен сайта"),
+    }, async (params) => {
+        const body = { name: params.name };
+        if (params.domain)
+            body.domain = params.domain;
+        const result = await api.post("remarketing/counters.json", body);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_delete_remarketing_counter", "Удалить счётчик ремаркетинга.", {
+        id: z.number().describe("ID счётчика для удаления"),
+    }, async (params) => {
+        const result = await api.delete(`remarketing/counters/${params.id}.json`);
+        return { content: [{ type: "text", text: JSON.stringify(result ?? { success: true }, null, 2) }] };
+    });
+}

package/dist/tools/statistics.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { VkAdsApi } from "../vk-api.js";
+export declare function registerStatisticsTools(server: McpServer, api: VkAdsApi): void;

package/dist/tools/statistics.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+export function registerStatisticsTools(server, api) {
+    server.tool("vk_get_statistics", "Получить статистику по кампаниям, группам объявлений или баннерам. Возвращает показы, клики, расходы, CTR и другие метрики.", {
+        object_type: z
+            .enum(["ad_plans", "ad_groups", "banners"])
+            .describe("Тип объекта: ad_plans (кампании), ad_groups (группы), banners (баннеры)"),
+        time_mode: z
+            .enum(["day", "hour", "summary"])
+            .describe("Режим времени: day (по дням), hour (по часам), summary (итого)"),
+        id: z.string().describe("ID объектов через запятую: 123,456"),
+        date_from: z.string().describe("Дата начала в формате YYYY-MM-DD"),
+        date_to: z.string().describe("Дата окончания в формате YYYY-MM-DD"),
+        metrics: z
+            .string()
+            .optional()
+            .describe("Метрики через запятую или 'all' для всех. Примеры: impressions,clicks,spent,ctr"),
+    }, async (params) => {
+        const endpoint = `statistics/${params.object_type}/${params.time_mode}.json`;
+        const query = {
+            id: params.id,
+            date_from: params.date_from,
+            date_to: params.date_to,
+        };
+        if (params.metrics)
+            query.metrics = params.metrics;
+        const result = await api.get(endpoint, query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/targeting.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { VkAdsApi } from "../vk-api.js";
+export declare function registerTargetingTools(server: McpServer, api: VkAdsApi): void;

package/dist/tools/targeting.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+export function registerTargetingTools(server, api) {
+    server.tool("vk_get_regions", "Получить список регионов для таргетинга.", {
+        q: z.string().optional().describe("Поисковый запрос для фильтрации регионов"),
+        limit: z.number().optional().describe("Макс. кол-во результатов"),
+        offset: z.number().optional().describe("Смещение"),
+    }, async (params) => {
+        const query = {};
+        if (params.q)
+            query.q = params.q;
+        if (params.limit)
+            query.limit = String(params.limit);
+        if (params.offset)
+            query.offset = String(params.offset);
+        const result = await api.get("regions.json", query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_get_interests", "Получить список категорий интересов для таргетинга.", {
+        limit: z.number().optional().describe("Макс. кол-во результатов"),
+        offset: z.number().optional().describe("Смещение"),
+    }, async (params) => {
+        const query = {};
+        if (params.limit)
+            query.limit = String(params.limit);
+        if (params.offset)
+            query.offset = String(params.offset);
+        const result = await api.get("interests.json", query);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    server.tool("vk_get_projection", "Оценить размер аудитории по параметрам таргетинга. Возвращает прогнозируемый охват.", {
+        targeting: z.string().describe("JSON с параметрами таргетинга (регионы, пол, возраст, интересы и т.д.)"),
+    }, async (params) => {
+        const body = JSON.parse(params.targeting);
+        const result = await api.post("projection.json", body);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/vk-api.d.ts

@@ -0,0 +1,13 @@
+export interface VkApiConfig {
+    accessToken: string;
+    proxyUrl: string;
+}
+export declare class VkAdsApi {
+    private config;
+    constructor(config: VkApiConfig);
+    private buildMethod;
+    private request;
+    get(endpoint: string, queryParams?: Record<string, string>): Promise<unknown>;
+    post(endpoint: string, body: Record<string, unknown>, queryParams?: Record<string, string>): Promise<unknown>;
+    delete(endpoint: string, queryParams?: Record<string, string>): Promise<unknown>;
+}

package/dist/vk-api.js

@@ -0,0 +1,51 @@
+export class VkAdsApi {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    buildMethod(endpoint, queryParams) {
+        let method = `/api/v2/${endpoint}`;
+        if (queryParams) {
+            const entries = Object.entries(queryParams).filter(([, v]) => v !== undefined && v !== null && v !== "");
+            if (entries.length > 0) {
+                const qs = entries.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
+                method += `?${qs}`;
+            }
+        }
+        return method;
+    }
+    async request(method, params) {
+        const body = new FormData();
+        body.append("method", method);
+        body.append("access_token", this.config.accessToken);
+        if (params && Object.keys(params).length > 0) {
+            body.append("params", JSON.stringify(params));
+        }
+        const response = await fetch(this.config.proxyUrl, {
+            method: "POST",
+            body,
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`VK Ads API HTTP ${response.status}: ${text}`);
+        }
+        const data = await response.json();
+        if (data && typeof data === "object" && "error" in data) {
+            const err = data;
+            throw new Error(`VK Ads API error ${err.error.code ?? "unknown"}: ${err.error.message ?? JSON.stringify(err.error)}`);
+        }
+        return data;
+    }
+    async get(endpoint, queryParams) {
+        const method = this.buildMethod(endpoint, queryParams);
+        return this.request(method);
+    }
+    async post(endpoint, body, queryParams) {
+        const method = this.buildMethod(endpoint, queryParams);
+        return this.request(method, body);
+    }
+    async delete(endpoint, queryParams) {
+        const method = this.buildMethod(endpoint, queryParams);
+        return this.request(method, { _method: "DELETE" });
+    }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "vk-ads-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for managing VK Ads campaigns through Claude",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "vk-ads-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "npx tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "tsx": "^4.19.0"
+  }
+}