yandex-direct

mcp-server-yandex-direct

适用于 Yandex Direct API v5 的 MCP 服务、CLI 工具和 Pydantic 模型库。

• MCP 服务 — 与 Claude Code、Claude Desktop 和其他 MCP 客户端集成
• CLI 工具 — 在终端中使用 API、编写脚本和自动化
• Pydantic 模型 — 可在自己的 Python 程序中使用的类型化 API 模型

所有数据都保留在您的计算机上，令牌不会传送到任何地方。

目录

• 架构
• 可用操作
• MCP 服务
  • 安装
  • 连接到 Claude Code
  • 连接到 Claude Desktop
  • 通过 --mcp-config 连接
  • 示例
• CLI 工具
  • 安装
  • 使用方法
  • 命令示例
• Pydantic 模型
  • 安装
  • 在自己的程序中使用
• 环境变量
• 开发
• 许可证

架构

服务采用 search + execute 模式，不提供 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	8	广告系列：创建、管理、归档
adgroups	4	广告组
ads	9	广告：创建、管理、审核
keywords	6	关键词
bidding	7	出价和出价调整
assets	11	快速链接、图片、视频、扩展
audience	10	受众和再营销
negkeywords	4	共享否定关键词列表
feeds	4	动态广告信息流
creatives	2	展示广告创意
research	2	关键词研究
leads	1	潜在客户开发表单中的线索
changes	3	变更跟踪
account	6	账户、参考数据、代理商客户
turbopages	1	Turbo 页面
reports	1	报告（TSV/CSV）

---

MCP 服务

安装

步骤 1. 获取 OAuth 令牌

1. 登录 Яндекс Директ
2. 前往 设置 → API
3. 创建具有所需权限的 OAuth 令牌
4. 复制令牌

步骤 2. 连接 MCP 服务

连接到 Claude Code

方式 1：通过 uvx（无需安装软件包）

需要 uv；如果尚未安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

claude mcp add yandex-direct \
  -e YD_TOKEN=ваш_токен \
  -- uvx mcp-server-yandex-direct

方式 2：通过 pip

pip install mcp-server-yandex-direct

claude mcp add yandex-direct \
  -e YD_TOKEN=ваш_токен \
  -- python -m mcp_server_yandex_direct

卸载：

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：

{
  "mcpServers": {
    "yandex-direct": {
      "command": "uvx",
      "args": ["mcp-server-yandex-direct"],
      "env": {
        "YD_TOKEN": "ваш_токен"
      }
    }
  }
}

通过 pip（执行 pip install mcp-server-yandex-direct 后）：

{
  "mcpServers": {
    "yandex-direct": {
      "command": "python",
      "args": ["-m", "mcp_server_yandex_direct"],
      "env": {
        "YD_TOKEN": "ваш_токен"
      }
    }
  }
}

Подключение через --mcp-config

Подключает сервер только на время одной сессии Claude, не сохраняя в настройки. Токен хранится в отдельном .env.mcp файле, а не в конфиге Claude.

Из JSON-строки:

claude --mcp-config '{"yandex-direct":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-yandex-direct"]}}'

Из файла:

claude --mcp-config ~/mcp-servers.json

Пример ~/mcp-servers.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)

pip install mcp-server-yandex-direct

Переменная окружения YD_TOKEN должна быть установлена:

export YD_TOKEN=ваш_токен

Или через файл:

mcp-server-yandex-direct --env /path/to/.env <command>

Формат файла — KEY=VALUE, по одной переменной на строку, #-комментарии.

Использование (CLI)

Без аргументов запускается MCP-сервер, с командой — CLI. Все команды выводят JSON.

# Версия
mcp-server-yandex-direct --version

# Справка
mcp-server-yandex-direct --help
mcp-server-yandex-direct <command> --help

Примеры команд

# Кампании
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"}}'

Пример вывода

$ mcp-server-yandex-direct campaigns-get '{"SelectionCriteria": {"States": ["ON"]}, "FieldNames": ["Id", "Name"]}'
{"Campaigns": [{"Id": 12345, "Name": "Летняя распродажа"}]}

---

Pydantic-модели

Пакет содержит типизированные Pydantic-модели всех объектов API. Модели можно использовать в своих Python-программах для валидации данных и автодополнения в IDE.

Установка (библиотеки)

pip install mcp-server-yandex-direct

Использование в своих программах

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)  # type-safe доступ к полям

Все модели используют extra="allow" для forward compatibility — неизвестные поля API не вызывают ошибок.

Полный список моделей: models/

---

Переменные окружения

Переменная	Обязательная	По умолчанию	Описание
YD_TOKEN	да	—	OAuth-токен Yandex Direct API
YD_CLIENT_LOGIN	нет	—	Логин клиента для агентских аккаунтов
YD_LANG	нет	—	Язык ответов: ru, en, uk
YD_TIMEOUT	нет	30	Таймаут HTTP-запросов к API (секунды)
YD_FILE_TIMEOUT	нет	120	Таймаут отчётов Reports API (секунды)

Разработка

pip install -e ".[test]"
ruff check src/ tests/
pytest tests/ -v

Лицензия

MIT