内容
# Yandex.Direct MCP
**用于 Yandex.Direct API v5 (+ Wordstat) 的 MCP 服务器。** 48 种工具可直接在 Claude、Cursor 和任何支持 [Model Context Protocol](https://modelcontextprotocol.io) 的客户端中管理上下文广告。
创建和编辑活动、分组、广告、关键词、竞价、扩展和否定关键词，收集报告和 Wordstat 频率 - 使用自然语言，无需手动点击 Direct 界面。
---
## 功能
- **活动、分组、广告** - 完整的 CRUD + 状态（启动/暂停/存档/审核）
- **关键词和竞价** - 批量添加、更新、竞价、自动定位
- **否定关键词** - 活动级别的否定短语集
- **扩展** - 快速链接（sitelinks）和说明（callouts）
- **报告** - 活动统计、搜索查询报告、自定义报告
- **Wordstat** - 关键词频率（通过 API v4）
- **词典** - Direct 地区和词典
- **多个账户** - 运行时在账户之间切换
- **沙盒和生产环境** - 一个标志切换环境
完整的 API 和格式文档请参见 [`docs/yandex-direct-api.md`](docs/yandex-direct-api.md)。
---
## 要求
- **Python 3.10+**
- **访问 Yandex.Direct API** 和 OAuth 令牌（获取方式见下文）
---
## 安装
```bash
git clone https://github.com/demokrat90/yandex-direct-mcp.git
cd yandex-direct-mcp
python -m venv .venv
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# Linux / macOS:
source .venv/bin/activate
pip install -r requirements.txt
```
---
## 获取 OAuth 令牌
Yandex.Direct API 使用 OAuth 令牌。获取令牌只需几分钟：
1. **创建 OAuth 应用程序** 在 <https://oauth.yandex.ru/client/new> 上：
- 在访问权限中选择 **Yandex.Direct** （管理活动）；
- 应用程序类型为“Web 服务”，重定向 URI 可以保留默认值。
- 创建后复制 **ClientID** 和 **Client secret**。
2. **填写它们** 在 `.env` 中（见下文）`YANDEX_DIRECT_CLIENT_ID` 和 `YANDEX_DIRECT_CLIENT_SECRET`。
3. **运行脚本** - 它将打开浏览器，您将确认访问，插入代码，令牌将保存在 `.env` 中：
```bash
python scripts/get_yandex_token.py
```
> 生产环境 API 需要批准的 Direct 访问权限。申请和条件：<https://yandex.ru/dev/direct/>。沙盒环境（`YANDEX_DIRECT_SANDBOX=true`）立即生效，不消耗积分。
---
## 配置
```bash
cp .env.example .env # Windows: copy .env.example .env
```
至少需要填写 `YANDEX_DIRECT_TOKEN`。其他变量请参见 [`.env.example`](.env.example)。
检查连接：
```bash
python scripts/test_yandex_connection.py # 沙盒环境
python scripts/test_yandex_connection.py --prod # 生产环境 API
```
---
## 连接到 MCP 客户端
将服务器添加到客户端配置中（模板参见 [`.mcp.example.json`](.mcp.example.json)）。
**Claude Desktop** - `claude_desktop_config.json`，**Cursor** - `.cursor/mcp.json`，**Claude Code** - `.mcp.json`:
```json
{
"mcpServers": {
"yandex-direct": {
"command": "python",
"args": ["/ABSOLUTE/PATH/TO/yandex-direct-mcp/run_server.py"],
"env": {
"YANDEX_DIRECT_TOKEN": "您的 OAuth 令牌",
"YANDEX_DIRECT_SANDBOX": "false"
}
}
}
}
```
> **Windows:** 在 `command` 中指定虚拟环境中的 Python 路径，例如 `C:/path/to/yandex-direct-mcp/.venv/Scripts/python.exe`，在 `args` 中指定 `run_server.py` 的完整路径。
重启客户端 - `yd_*` 工具将出现在列表中。
---
## 多个账户
一个服务器服务多个账户。在 `.env` 中指定它们：
```
YANDEX_DIRECT_ACCOUNTS=main,client2
YANDEX_DIRECT_ACCOUNT_MAIN_TOKEN=...
YANDEX_DIRECT_ACCOUNT_MAIN_DESC=主要账户
YANDEX_DIRECT_ACCOUNT_CLIENT2_TOKEN=...
YANDEX_DIRECT_ACCOUNT_CLIENT2_DESC=客户 2
YANDEX_DIRECT_DEFAULT_ACCOUNT=main
```
运行时：`yd_list_accounts` - 列表，`yd_switch_account` - 切换。
---
## 工具（48）
| 类别 | 工具 |
|---|---|
| **账户** （3） | `yd_list_accounts`，`yd_switch_account`，`yd_get_account_info` |
| **活动** （9） | `yd_get_campaigns`，`yd_create_campaign`，`yd_create_campaigns`，`yd_update_campaigns`，`yd_delete_campaigns`，`yd_suspend_campaigns`，`yd_resume_campaigns`，`yd_archive_campaigns`，`yd_unarchive_campaigns` |
| **分组** （5） | `yd_get_ad_groups`，`yd_create_ad_group`，`yd_create_ad_groups`，`yd_update_ad_group`，`yd_delete_ad_groups` |
| **广告** （8） | `yd_get_ads`，`yd_create_text_ad`，`yd_create_text_ads`，`yd_update_ads`，`yd_delete_ads`，`yd_moderate_ads`，`yd_suspend_ads`，`yd_resume_ads` |
| **关键词** （5） | `yd_get_keywords`，`yd_add_keywords`，`yd_add_keywords_bulk`，`yd_update_keywords`，`yd_delete_keywords` |
| **竞价** （2） | `yd_get_keyword_bids`，`yd_set_keyword_bids` |
| **自动定位** （1） | `yd_update_autotargeting` |
| **否定关键词** （2） | `yd_get_negative_keyword_sets`，`yd_create_negative_keyword_set` |
| **扩展** （6） | `yd_get_sitelinks`，`yd_create_sitelinks`，`yd_delete_sitelinks`，`yd_create_callouts`，`yd_get_ad_extensions`，`yd_delete_extensions` |
| **报告** （3） | `yd_campaign_performance_report`，`yd_search_query_report`，`yd_custom_report` |
| **Wordstat** （1） | `yd_wordstat_report` |
| **词典** （2） | `yd_get_regions`，`yd_get_dictionaries` |
| **更改** （1） | `yd_check_changes` |
---
## 广告格式限制
| 字段 | 限制 |
|---|---|
| 标题 1 | 56 个字符 |
| 标题 2 | 30 个字符 |
| 文本 | 81 个字符 |
| 快速链接标题 | 30 个字符 |
| 说明（callout） | 25 个字符 |
| 一组快速链接 | 最多 8 个 |
有用的地区 ID：`225` - 俄罗斯，`213` - 莫斯科，`2` - 圣彼得堡，`0` - 全球。通过 `yd_get_regions` 获取完整列表。
---
## 架构
```
run_server.py # 入口点：加载 .env 并启动服务器
yandex_direct/
├── server.py # MCP 服务器（list_tools / call_tool，多账户）
├── tools.py # 所有 48 个工具：定义 + 处理程序
├── api_client.py # HTTP 客户端 API v5（JSON），sandbox/production
├── client.py # YandexDirectManager 服务的 facade
└── *_service.py # 活动/分组/广告/关键词/扩展的服务
scripts/
├── get_yandex_token.py # OAuth 流（浏览器 → 代码 → 令牌）
└── test_yandex_connection.py # 连接测试
```
---
## 限制和支持
该项目按“原样”提供。欢迎提出问题和拉取请求，但不保证定期支持和 SLA。如果某些功能不正常，请在问题中提供重现步骤。
---
## 关于作者
由 **Verkhozin Marketing** 制作 - 上下文广告设置和自动化（Google Ads，Yandex.Direct）。
如果您需要广告或基于 AI 的自动化帮助，请通过 [GitHub](https://github.com/demokrat90) 或在存储库中提出问题。
---
## 许可证
[MIT](LICENSE) © 2026 Verkhozin Marketing
