内容
# yandex-direct-mcp
生产级别、开源的软件开发工具包（SDK）和 [MCP](https://modelcontextprotocol.io) 服务器，适用于
[Yandex Direct API v5](https://yandex.ru/dev/direct/doc/dg/concepts/about.html)。
> **状态：** 早期开发。传输、身份验证和配置层，Campaigns/Keywords/Reports 服务以及 MCP 服务器已经实现并测试完毕。`campaigns.add`/`update`（需要特定于广告活动类型的设置对象）尚未实现。
## 目标
- 一个类型化的、异步优先的 Python SDK，用于 Yandex Direct API v5。
- 一个 MCP 服务器，公开广告活动/关键词/报告操作作为工具，以便 LLM 代理（例如 Claude Desktop）可以检查和管理广告帐户。
- 严格的工程标准：完整的类型覆盖，没有存根，每个模块的测试，传输、服务和 MCP 工具之间的清晰架构边界。
## 安装
```bash
poetry install
```
## 配置
客户端可以通过显式或环境变量进行配置：
```python
from yandex_direct import YandexDirectClient, YandexDirectConfig
config = YandexDirectConfig(access_token="<oauth-token>")
# 或：config = YandexDirectConfig.from_env()
with YandexDirectClient(config) as client:
...
```
识别环境变量：
| 变量 | 是否必需 | 描述 |
|----------------------------------------|----------|-----------------------------------------------|
| `YANDEX_DIRECT_ACCESS_TOKEN` | 是 | Yandex Direct 应用程序的 OAuth 令牌 |
| `YANDEX_DIRECT_CLIENT_LOGIN` | 否 | 代替客户登录（代理机构） |
| `YANDEX_DIRECT_USE_OPERATOR_UNITS` | 否 | 计费点到操作员帐户 |
| `YANDEX_DIRECT_LANGUAGE` | 否 | 错误消息语言（`ru`、`en`、`uk`） |
| `YANDEX_DIRECT_SANDBOX` | 否 | 目标 API 沙盒环境 |
## MCP 服务器
该软件包安装了一个 MCP 服务器，公开广告活动、关键词和报告作为工具，供 MCP 客户端（如 Claude Desktop）使用。
设置 `YANDEX_DIRECT_ACCESS_TOKEN`（和可选的 `YANDEX_DIRECT_CLIENT_LOGIN`、`YANDEX_DIRECT_SANDBOX`；参见 [配置](#配置)），然后运行：
```bash
poetry run yandex-direct-mcp
# 或：poetry run python -m yandex_direct.mcp
```
服务器通过标准输入/输出通信。要将其与 Claude Desktop 一起使用，请将其添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"yandex-direct": {
"command": "poetry",
"args": ["run", "yandex-direct-mcp"],
"cwd": "/path/to/yandex-direct-mcp",
"env": { "YANDEX_DIRECT_ACCESS_TOKEN": "<oauth-token>" }
}
}
}
```
可用工具：
| 工具 | 描述 |
|-------------------------|-------------------------------------------------------|
| `list_campaigns` | 列出广告活动，可选过滤 |
| `suspend_campaigns` | 停止显示给定广告活动的广告 |
| `resume_campaigns` | 恢复暂停的广告活动的广告投放 |
| `archive_campaigns` | 存档停止的广告活动 |
| `unarchive_campaigns` | 从存档中恢复广告活动 |
| `delete_campaigns` | 永久删除存档的广告活动 |
| `list_keywords` | 列出关键词，可选过滤 |
| `add_keywords` | 将关键词添加到广告组 |
| `update_keyword_bid` | 更改关键词的手动出价 |
| `suspend_keywords` | 停止显示给定关键词的广告 |
| `resume_keywords` | 恢复暂停的关键词的广告投放 |
| `delete_keywords` | 永久删除关键词 |
| `get_report` | 获取性能报告，轮询直到报告就绪 |
## 开发
```bash
poetry install
ruff check .
black --check .
mypy src
pytest
```
## 许可证
MIT
