内容
<!-- mcp-name: io.github.dontsovcmc/yandex-direct -->
# Yandex Direct MCP 服务器
[](https://github.com/dontsovcmc/mcp-server-yandex-direct)
MCP 服务器、CLI 工具和 Pydantic 模型库，用于 [Yandex Direct API v5](https://yandex.ru/dev/direct/doc/concepts/about.html)。
- **MCP 服务器** — 与 Claude Code、Claude Desktop 等 MCP 客户端集成
- **CLI 工具** — 从终端、脚本和自动化中使用 API
- **Pydantic 模型** — 用于 Python 程序中的 API 类型化模型
所有数据都存储在您的计算机上 — 令牌不会被传输到任何地方。
## 目录
- [架构](#架构)
- [可用操作](#可用操作-79)
- [MCP 服务器](#mcp服务器)
- [安装](#安装)
- [连接到 Claude Code](#连接到-claude-code)
- [连接到 Claude Desktop](#连接到-claude-desktop)
- [通过 --mcp-config 连接](#通过--mcp-config-连接)
- [示例](#示例-mcp)
- [CLI 工具](#cli工具)
- [安装](#安装-cli)
- [使用](#使用-cli)
- [命令示例](#命令示例)
- [Pydantic 模型](#pydantic模型)
- [安装](#安装库)
- [在您自己的程序中使用](#在您自己的程序中使用)
- [环境变量](#环境变量)
- [开发](#开发)
- [许可证](#许可证)
## 架构
服务器使用 **搜索 + 执行** 模式 — 而不是 79 个单独的工具，而是提供 2 个：
| 工具 | 描述 |
| --- | --- |
| `yd_search` | 根据自然语言描述搜索操作 |
| `yd_execute` | 根据 ID 执行操作 |
### 工作原理
```
LLM: yd_search("停止活动")
→ [{"id": "campaigns-suspend", "params_schema": {"SelectionCriteria": {...}, ...}, ...}]
LLM: yd_execute("campaigns-suspend", '{"SelectionCriteria": {"Ids": [12345]}}')
→ {"SuspendResults": [...]}
```
## 可用操作（79）
| 域 | 数量 | 描述 |
| --- | --- | --- |
| [`campaigns`](docs/campaigns.md) | 8 | 活动：创建、管理、存档 |
| [`adgroups`](docs/adgroups.md) | 4 | 广告组 |
| [`ads`](docs/ads.md) | 9 | 广告：创建、管理、审核 |
| [`keywords`](docs/keywords.md) | 6 | 关键词 |
| [`bidding`](docs/bidding.md) | 7 | 出价和出价调整 |
| [`assets`](docs/assets.md) | 11 | 快速链接、图片、视频、扩展 |
| [`audience`](docs/audience.md) | 10 | 受众和再定位 |
| [`negkeywords`](docs/negkeywords.md) | 4 | 通用否定关键词列表 |
| [`feeds`](docs/feeds.md) | 4 | 动态广告的 feed |
| [`creatives`](docs/creatives.md) | 2 | 媒体广告的创意 |
| [`research`](docs/research.md) | 2 | 关键词研究 |
| [`leads`](docs/leads.md) | 1 | 来自引流表单的线索 |
| [`changes`](docs/changes.md) | 3 | 跟踪更改 |
| [`account`](docs/account.md) | 6 | 账户、目录、代理商客户 |
| [`turbopages`](docs/turbopages.md) | 1 | 涡轮页面 |
| [`reports`](docs/reports.md) | 1 | 报告（TSV/CSV） |
---
## MCP 服务器
### 安装
#### 步骤 1：获取 OAuth 令牌
1. 登录 [Yandex Direct](https://direct.yandex.ru/)
2. 转到 **设置** → **API**
3. 创建具有所需权限的 OAuth 令牌
4. 复制令牌
#### 步骤 2：连接 MCP 服务器
### 连接到 Claude Code
**方法 1：通过 uvx**（不需要安装软件包）
> 需要 [uv](https://docs.astral.sh/uv/) — 如果未安装：
> ```bash
> curl -LsSf https://astral.sh/uv/install.sh | sh
> ```
```bash
claude mcp add yandex-direct \
-e YD_TOKEN=您的令牌 \
-- uvx mcp-server-yandex-direct
```
**方法 2：通过 pip**
```bash
pip install mcp-server-yandex-direct
claude mcp add yandex-direct \
-e YD_TOKEN=您的令牌 \
-- python -m mcp_server_yandex_direct
```
要删除：
```bash
claude mcp remove yandex-direct
```
### 连接到 Claude Desktop
将以下内容添加到配置文件中：
| 客户端 | 操作系统 | 文件路径 |
| --- | --- | --- |
| Claude Code | 全部 | `~/.claude/settings.json`（`mcpServers` 部分） |
| Claude Desktop | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Desktop | Linux | `~/.config/Claude/claude_desktop_config.json` |
**通过 uvx：**
```json
{
"mcpServers": {
"yandex-direct": {
"command": "uvx",
"args": ["mcp-server-yandex-direct"],
"env": {
"YD_TOKEN": "您的令牌"
}
}
}
}
```
**通过 pip**（在 `pip install mcp-server-yandex-direct` 之后）：
```json
{
"mcpServers": {
"yandex-direct": {
"command": "python",
"args": ["-m", "mcp_server_yandex_direct"],
"env": {
"YD_TOKEN": "您的令牌"
}
}
}
}
```
### 通过 --mcp-config 连接
仅在 Claude 会话期间连接服务器，而不保存到设置中。令牌存储在单独的 `.env.mcp` 文件中，而不是 Claude 配置文件中。
从 JSON 字符串：
```bash
claude --mcp-config '{"yandex-direct":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-yandex-direct"]}}'
```
从文件：
```bash
claude --mcp-config ~/mcp-servers.json
```
`~/mcp-servers.json` 示例：
```json
{
"yandex-direct": {
"command": "bash",
"args": ["-c", "source ~/.env.mcp && exec uvx mcp-server-yandex-direct"]
}
}
```
`.env.mcp` 示例：
```
YD_TOKEN=您的令牌
```
#### 步骤 3：检查
询问 Claude：*「显示活动列表」* — 它将调用 `yd_search`，获取 `campaigns-get` 模式，然后调用 `yd_execute`。
### 示例（MCP）
Claude 自动使用 `yd_search` 搜索所需操作，然后使用 `yd_execute` 执行该操作：
- 「显示所有活跃活动」→ `yd_search("活动")` → `yd_execute("campaigns-get", ...)`
- 「停止活动 123, 456」→ `yd_search("停止活动")` → `yd_execute("campaigns-suspend", ...)`
- 「显示活动 789 的广告」→ `yd_search("广告")` → `yd_execute("ads-get", ...)`
- 「添加关键词」→ `yd_search("添加关键词")` → `yd_execute("keywords-add", ...)`
- 「获取目录」→ `yd_search("目录")` → `yd_execute("dictionaries-get", ...)`
- 「生成活动报告」→ `yd_search("报告")` → `yd_execute("reports-get", ...)`
---
## CLI 工具
### 安装（CLI）
```bash
pip install mcp-server-yandex-direct
```
环境变量 `YD_TOKEN` 必须设置：
```bash
export YD_TOKEN=您的令牌
```
或通过文件：
```bash
mcp-server-yandex-direct --env /path/to/.env <command>
```
文件格式 — `KEY=VALUE`，每行一个变量，`#` 为注释。
### 使用（CLI）
不带参数启动为 MCP 服务器，带命令启动为 CLI。所有命令输出 JSON。
```bash
# 版本
mcp-server-yandex-direct --version
# 帮助
mcp-server-yandex-direct --help
mcp-server-yandex-direct <command> --help
```
### 命令示例
```bash
# 活动
mcp-server-yandex-direct campaigns-get '{"SelectionCriteria": {}, "FieldNames": ["Id", "Name", "State"]}'
mcp-server-yandex-direct campaigns-suspend 123,456
# 广告
mcp-server-yandex-direct ads-get '{"SelectionCriteria": {"CampaignIds": [123]}, "FieldNames": ["Id", "Type", "State"]}'
mcp-server-yandex-direct ads-moderate 789,101
# 关键词
mcp-server-yandex-direct keywords-get '{"SelectionCriteria": {"AdGroupIds": [111]}, "FieldNames": ["Id", "Keyword", "State"]}'
# 目录
mcp-server-yandex-direct dictionaries-get Currencies,Regions
# 报告
mcp-server-yandex-direct reports-get '{"params": {"SelectionCriteria": {"DateFrom": "2026-01-01", "DateTo": "2026-04-28"}, "FieldNames": ["Date", "CampaignId", "Clicks", "Cost"], "ReportName": "My Report", "ReportType": "CAMPAIGN_PERFORMANCE_REPORT", "DateRangeType": "CUSTOM_DATE", "Format": "TSV"}}'
```
#### 输出示例
```bash
$ mcp-server-yandex-direct campaigns-get '{"SelectionCriteria": {"States": ["ON"]}, "FieldNames": ["Id", "Name"]}'
{"Campaigns": [{"Id": 12345, "Name": "夏季促销"}]}
```
---
## Pydantic 模型
该软件包包含所有 API 对象的类型化 Pydantic 模型。可以在 Python 程序中使用这些模型进行数据验证和 IDE 自动补全。
### 安装（库）
```bash
pip install mcp-server-yandex-direct
```
### 在您自己的程序中使用
```python
from mcp_server_yandex_direct.models.campaigns import CampaignsGetParams, CampaignsSelectionCriteria
# 验证 API 数据
params = CampaignsGetParams(
SelectionCriteria=CampaignsSelectionCriteria(States=["ON"]),
FieldNames=["Id", "Name", "State"],
)
print(params.model_dump_json())
# 验证响应
from mcp_server_yandex_direct.models.campaigns import CampaignsGetResult
data = {"Campaigns": [{"Id": 12345, "Name": "测试", "State": "ON"}]}
result = CampaignsGetResult.model_validate(data)
print(result.Campaigns[0].Name) # 类型安全的字段访问
```
所有模型都使用 `extra="allow"` 进行前向兼容 — 未知的 API 字段不会引发错误。
模型列表： [`models/`](src/mcp_server_yandex_direct/models/)
---
## 环境变量
| 变量 | 必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `YD_TOKEN` | 是 | - | Yandex Direct API 的 OAuth 令牌 |
| `YD_CLIENT_LOGIN` | 否 | - | 代理商账户的客户端登录名 |
| `YD_LANG` | 否 | - | 答案语言： `ru`，`en`，`uk` |
| `YD_TIMEOUT` | 否 | `30` | API 请求超时（秒） |
| `YD_FILE_TIMEOUT` | 否 | `120` | 报告 API 超时（秒） |
## 开发
```bash
pip install -e ".[test]"
ruff check src/ tests/
pytest tests/ -v
```
## 许可证
MIT
