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. Yandex Direct にログインします
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 への接続

設定ファイルに追加します：

クライアント	OS	ファイルパス
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