Yandex Direct MCP

yandex-direct-mcp

Yandex Direct API v5 用の MCP サーバーです。キャンペーン、広告グループ、 広告、キーワード、入札単価、入札単価調整、サイトリンク、vCard、レポートに対応しています。ツール数は 43 です。

書き込みアクセスがあり、ドライランはありません。 このモノレポ内の他のサーバーとは異なり、このサーバーは 実際の広告データを変更します。キャンペーンや広告の作成、更新、削除、アーカイブ、入札単価の設定が可能です（マイクロ単位のため、 1,000,000 倍の間違いには実際のリスクがあります）。確認ステップもドライランモードもありません。 ワークフローを信頼できるようになるまでは、サンドボックス（YANDEX_DIRECT_SANDBOX=true）を指定してください。

インストール

このパッケージは @stufently/yandex-direct-mcp として公開されています。公開レジストリ上のスコープなしの yandex-*-mcp 名は、無関係な公開者のものです（ルート README の注記を参照）。まだスコープには何も公開されていないため、ソースから実行してください。

git clone https://github.com/stufently/yandex-mcp.git
cd yandex-mcp && bun install
node packages/yandex-direct-mcp/src/index.mjs

設定

変数	必須	説明
YANDEX_DIRECT_TOKEN	はい	Direct API v5 用の OAuth トークン
YANDEX_DIRECT_CLIENT_LOGIN	代理店のみ	代理で操作するクライアントのログイン
YANDEX_DIRECT_SANDBOX	いいえ	true にすると、呼び出しを Direct サンドボックスにルーティングします

{
  "mcpServers": {
    "yandex-direct": {
      "command": "node",
      "args": ["/path/to/yandex-mcp/packages/yandex-direct-mcp/src/index.mjs"],
      "env": { "YANDEX_DIRECT_TOKEN": "your-token" }
    }
  }
}

ツール

領域	ツール
キャンペーン	get_campaigns、add_campaigns、update_campaigns、delete_campaigns、archive_campaigns、unarchive_campaigns、suspend_campaigns、resume_campaigns
広告グループ	get_adgroups、add_adgroups、update_adgroups、delete_adgroups、archive_adgroups、unarchive_adgroups
広告	get_ads、add_ads、update_ads、delete_ads、archive_ads、unarchive_ads、moderate_ads
キーワード	get_keywords、add_keywords、update_keywords、delete_keywords、suspend_keywords、resume_keywords
入札単価	get_keyword_bids、set_keyword_bids、set_auto_keyword_bids、get_bid_modifiers、add_bid_modifiers、set_bid_modifiers、delete_bid_modifiers
拡張機能	get_sitelinks、add_sitelinks、delete_sitelinks、get_vcards、add_vcards、delete_vcards
その他	create_report、get_dictionaries、get_clients

取り消せないツールには confirm: true が必要です

14 個のツールはこの API を通じて取り消すことができず、誤った呼び出しによって実際に費用が発生するのは、このサーバーだけです。confirm: true を指定しない限り、これらのツールは呼び出しを拒否します。

ファミリー	ツール	取り消せない理由
削除	delete_campaigns、delete_adgroups、delete_ads、delete_keywords、delete_bid_modifiers、delete_sitelinks、delete_vcards	エンティティと、それに紐づく統計情報が失われます。add_* は新しい ID を持つ新しいエンティティを作成するため、元の状態には戻りません
更新	update_campaigns、update_adgroups、update_ads、update_keywords	フィールドはその場で上書きされ、Direct にはリビジョン履歴が公開されていないため、以前の広告文、予算、戦略を読み戻すことができません
入札	set_keyword_bids、set_auto_keyword_bids、set_bid_modifiers	同じく上書きされますが、価格に直結します。アカウントがクリックごとに支払う金額を決める値です

{ "ids": [12345], "confirm": true }

これを指定せずに呼び出すと、ツールはエラー結果を返し、Direct API には何も送信しません。エンティティにも入札額にも変更はなく、API ユニットも消費されません。

Refused: `delete_campaigns` requires explicit confirmation.

Target — IDs: 12345. Deleting campaigns is irreversible: they and their accumulated statistics
are gone for good, and Yandex Direct offers no way to restore them.

Nothing was sent to the Yandex Direct API — no campaign, ad, keyword or bid was touched, and no
API units were spent.

To go ahead, call `delete_campaigns` again with the same ids and `confirm: true`.
To see the current state first, call `get_campaigns`.

JSON スキーマで confirm を任意にしているのは意図的です。確認がない場合、モデルが対処できないスキーマ検証エラーではなく、理由の説明を返す必要があるためです。文字列どおりの true だけが有効です。"true"、1、"yes" は拒否されます。プロトコルについての推測は、費用をかけるという決断ではないためです。14 個すべてに MCP アノテーションで destructiveHint: true が設定されているため、ツールのリスクを表示するクライアントは呼び出し前にその情報を提示できます。

add_*、archive_*／unarchive_*、suspend_*／resume_*、moderate_ads は、意図的に保護対象から外しています。 それぞれにこのサーバー内で元に戻す手段があるか（moderate_ads の場合はエンティティ自体に変更を加えないため）、これらは損失ではなく変更だからです。すべての書き込みを保護すると、呼び出し側は反射的に confirm: true を渡すようになり、重要な14個の呼び出しで保護が機能しなくなります。

入札額の単位はマイクロ（×10⁶）です。実験中は YANDEX_DIRECT_SANDBOX=true を設定してください。

既知の制限事項

• API パスは /json/v5 にハードコードされているため、統合パフォーマンスキャンペーンのエンドポイント（v501）にはアクセスできません。
• Units レスポンスヘッダー（消費済み／残りのポイント）が表示されないため、クライアントは呼び出しにかかったクォータを確認できません。

ライセンス

MIT