内容
# 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 服务器：通过自然语言管理广告，支持 Claude、Cursor、Codex 等 AI 客户端。
助手自动从统计数据、广告活动、群体和广告中收集数据，查找规律并进行调整 - 这些工作在 VK 广告后台需要手动完成。
<img src="docs/demo.gif" alt="演示：助手调用 list_ad_plans、get_statistics 和 get_balance，并找到一个花费预算的广告活动" width="1000">
<sub>真正的 MCP 会话：实时服务器、握手和 stdio 调用；VK 广告的响应是录制的固定响应 (<a href="docs/demo">docs/demo</a>)，因此演示无需令牌和网络连接 - <a href="docs/demo.tape">vhs docs/demo.tape</a>。</sub>
## 快速开始
1. [获取令牌](#获取令牌) - 从 VK 广告后台获取 `client_id`/`client_secret`，并执行一个 curl 命令。
2. 添加服务器 - 例如，在 Claude Code 中（[其他客户端](#安装)）：
```bash
claude mcp add vk-ads -e VK_ADS_TOKEN=您的令牌 -- npx -y mcp-vk-ads
```
3. 向助手提问：“显示最近 7 天的广告活动统计数据”。
## 功能
- **广告活动、群体、广告** - 广告计划 (`ad_plans`)、群体 (`ad_groups`) 和广告 (`banners`)：列表、创建、更新、状态。
- **统计数据** - v3 统计服务报告，支持按天/周/月分组。
- **通用 `raw_request`** - 直接调用任意 VK 广告 API 接口。
- **仅需确认的写入操作** - `raw_request` 中的非 GET 请求（POST/DELETE）需要明确的 `confirmWrite=true`。
- **货币单位** - 预算、竞价和花费按账户货币（卢布）显示，无需换算；`get_balance` 显示账户余额。
- **`autoPaginate`** - 自动遍历所有分页，无需手动处理大型账户。
- **容错性** - 限额（429）和 5xx 错误重试，请求超时；`get_throttling` 显示 API 限额。
## 请求示例
向助手提问，例如：
- “显示最近 7 天的广告活动统计数据”
- “哪些广告花费了预算但没有转化？”
- “停止所有未通过审核的广告”
- “查找 Moscow 地区的 ID”
- “将广告活动 12345 的每日预算提高到 5000 卢布”
## 安装
配置您的客户端：
<details>
<summary><b>Claude Code</b></summary>
```bash
claude mcp add vk-ads -e VK_ADS_TOKEN=您的令牌 -- npx -y mcp-vk-ads
```
或者通过插件市场，令牌将通过对话框提示并保存在系统 keychain 中（不会在配置文件中以明文显示）：
```
/plugin marketplace add askads/claude-plugins
/plugin install vk-ads@askads
```
</details>
<details>
<summary><b>Claude Desktop</b></summary>
`claude_desktop_config.json` - macOS `~/Library/Application Support/Claude/`，Windows `%APPDATA%\Claude\`
```json
{
"mcpServers": {
"vk-ads": {
"command": "npx",
"args": ["-y", "mcp-vk-ads"],
"env": { "VK_ADS_TOKEN": "您的令牌" }
}
}
}
```
</details>
<details>
<summary><b>Cursor</b></summary>
`~/.cursor/mcp.json`（或 `.cursor/mcp.json` 在项目中）
```json
{
"mcpServers": {
"vk-ads": {
"command": "npx",
"args": ["-y", "mcp-vk-ads"],
"env": { "VK_ADS_TOKEN": "您的令牌" }
}
}
}
```
</details>
<details>
<summary><b>OpenAI Codex</b></summary>
使用命令：`codex mcp add vk-ads --env VK_ADS_TOKEN=您的令牌 -- npx -y mcp-vk-ads`
或在 `~/.codex/config.toml` 中：
```toml
[mcp_servers.vk-ads]
command = "npx"
args = ["-y", "mcp-vk-ads"]
[mcp_servers.vk-ads.env]
VK_ADS_TOKEN = "您的令牌"
```
</details>
<details>
<summary><b>VS Code</b></summary>
`.vscode/mcp.json` - 键 `servers`（不是 `mcpServers`）
```json
{
"servers": {
"vk-ads": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-vk-ads"],
"env": { "VK_ADS_TOKEN": "您的令牌" }
}
}
}
```
</details>
## 获取令牌
令牌由 VK 广告后台提供 - 无需第三方应用：
1. 在 [ads.vk.com](https://ads.vk.com) 后台打开 **设置 → API 访问** 并创建应用 - 获取 `client_id` 和 `client_secret`。（如果没有此部分，请联系 VK 广告支持。）
2. 使用 `client_credentials` 授权流程交换令牌：
```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
```
从响应中获取 `access_token` - 即 `VK_ADS_TOKEN`。
3. 当令牌过期（`invalid_token` 错误）时，使用相同的命令生成新令牌并重新配置。一个用户最多有 5 个活动令牌；旧令牌可以通过 `POST /api/v2/oauth2/token/delete.json` 请求撤销。
## 配置
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `VK_ADS_TOKEN` | 是 | - | VK 广告 OAuth2 访问令牌（Bearer）。 |
| `VK_ADS_LANG` | 否 | `ru` | `Accept-Language` 头部。 |
| `VK_ADS_TIMEOUT_MS` | 否 | `60000` | 请求超时，毫秒。 |
| `VK_ADS_MAX_RETRIES` | 否 | `3` | 临时错误（429，5xx）重试次数。 |
| `VK_ADS_API_BASE` | 否 | `https://ads.vk.com/api` | API 根地址（无版本）。 |
完整工具列表请参见 [docs/TOOLS.md](https://github.com/askads/mcp-vk-ads/blob/main/docs/TOOLS.md)。
## 要求
- Node.js 20+（通过 `npx` 运行，不需要单独安装）。
- VK 广告访问令牌 - 参见 [获取令牌](#获取令牌)。
## 限制
- VK 广告令牌会过期 - 当出现 `invalid_token` 错误时，请更新令牌并重新配置。
- VK 广告没有沙盒环境：所有调用都直接影响真实账户。通过 `raw_request` 写入操作受 `confirmWrite` 保护，但类型化 `*_action`/`update_*` 操作会立即修改数据。
- 创建群体和广告需要正确的 `targetings` / `content` / `textblocks` / `urls` 结构 - 格式取决于广告类型（参见 VK 广告文档）。
## 文档
- [所有工具](https://github.com/askads/mcp-vk-ads/blob/main/docs/TOOLS.md) - 完整列表及描述。
- [开发](https://github.com/askads/mcp-vk-ads/blob/main/docs/DEVELOPMENT.md) - 构建、测试、Smoke 测试。
## 参见
- **[Ask Ads](https://askads.ru)** - 由该服务器的作者提供的聊天分析工具和广告账户“守卫”：Telegram 中的预算支出和跟踪故障警报。
- **[askads/claude-plugins](https://github.com/askads/claude-plugins)** - Claude 插件市场：Ask Ads 服务器通过一个命令安装，令牌在启用时提示。
## 支持
问题、想法和改进请在 Telegram 上联系：[@gistrec](http://t.me/gistrec)。
## 许可证
MIT - 参见 [LICENSE](./LICENSE)。
