yandex-direct-mcp

Яндекс Директ API v5 用の MCP サーバー。広告アカウントを AI エージェント (Claude Code、Cursor、その他の MCP クライアント) に接続します。タスクは通常のテキストで設定され、エージェントが API 呼び出しを組み立て、応答を解析します。

Ты:    посмотри, куда за август ушёл бюджет и что откручивается без конверсий
Агент: [direct_report] → 12 кампаний, 340 фраз
       Расход 214 800 ₽. Кампания «Поиск / Бренд» — 38%, CPA 610 ₽.
       17 фраз потратили 31 400 ₽ при нуле конверсий — вот они, отключаем?

依存関係なし: Node.js 上の単一ファイル、stdio トランスポート、組み込みの fetch によるリクエスト。

• トークンはローカルに保存され、権限 600 のファイルに置かれ、api.direct.yandex.com 以外には送信されません。

• 変更は確認後に行われます。 MCP クライアントは各呼び出しの許可を求めます。さらに、サーバーレベルで変更メソッドをブロックする「読み取り専用」モードもあります。

• 完全な API、サブセットではありません。 汎用ツール direct_call は v5 のすべてのサービス (campaigns から keywordsresearch まで) をカバーします。

できること

分析。 任意の切り口と期間のレポート: キャンペーン、グループ、広告、キーフレーズ、検索クエリ、地域、デバイス、時間帯、性別、年齢。支出、クリック、CTR、CPC、コンバージョン、CPA、期間比較。検索クエリのゴミ分析、コンバージョンなしの支出フレーズの検索。

管理。 キャンペーン、グループ、広告、キーフレーズの作成と編集。入札単価と日次予算 — バッチ処理やルールによる設定も可能 (「CPA が 2000 ₽ を超える → 入札単価を 20% 削減」)。マイナスキーワード、有効化と停止、モデレーション送信、地域・デバイス・オーディエンス別の入札調整、リターゲティング。

セマンティクス。 フレーズの頻度確認 (keywordsresearch)、地域とタイムゾーンの辞書 (dictionaries)。

定期的なタスク。 昨日の支出の朝のサマリー、毎週の検索クエリ分析、過剰支出の通知 — MCP クライアントがスケジュールをサポートしている場合。

詳細なシナリオとリクエスト例: docs/usage.md。

Related MCP server: Yandex Direct MCP Server

要件

• Node.js 18 以降 (組み込みの fetch が必要)。

• Яндекс Директа アカウント。

• oauth.yandex.ru に登録されたアプリケーションで、API アクセスへの承認済み申請が必要。これが最大の障壁で、1 時間から 3 日かかります — ここから始めてください: docs/registration.md。

インストール

git clone https://github.com/iarbor04/yandex-direct-mcp.git
cd yandex-direct-mcp

依存関係はありません。npm install は不要です。

Claude Code:

claude mcp add yandex-direct --scope user -- node "$PWD/server.js"

Cursor、Windsurf、その他の JSON 設定を持つクライアント:

{
  "mcpServers": {
    "yandex-direct": {
      "command": "node",
      "args": ["/абсолютный/путь/yandex-direct-mcp/server.js"]
    }
  }
}

ツールはクライアントの起動時に表示されます — サーバーを追加したらセッションを再起動してください。

認証

順序が重要です。この順序で行わないと、エラー 58 が発生し、時間を無駄にします — 私たちは無駄にしました。

1. API アクセス申請

oauth.yandex.ru でアプリケーションを登録し、Direct のインターフェースで申請を提出します: 「申請一覧」。審査はロシアの営業日 10:00 から 19:00 で、1 時間から 3 日、ピーク時は最大 7 日かかります。

フォームに書く内容 (すべてのフィールドのテキスト、連携スキームの説明と図を含む) — docs/registration.md。

承認された申請なしではサンドボックスも動作しません。 確認済み: api-sandbox.direct.yandex.com は本番 API と同じエラー 58 を返します。「テストデータでデバッグする」ことはできません。

2. トークン

./save-token.sh <CLIENT_ID>

スクリプトは認証リンクを表示し、リダイレクト後のアドレスバーを貼り付けるのを待ちます (入力は非表示 — URL もトークンもシェルの履歴に残りません)。access_token を抽出し、~/.config/yandex-direct/token に権限 600 で保存し、すぐにアクセスチェックを実行します。

<CLIENT_ID> — 申請が承認されたアプリケーションの ID。スクリプトはそれを config.json に保存するので、以降は引数なしで実行できます。

手動でも同じ: https://oauth.yandex.ru/authorize?response_type=token&client_id=<CLIENT_ID> を開き、#access_token= の後 ( & の前) のトークンをアドレスバーから取得してファイルに保存します。

3. 確認

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"direct_status","arguments":{}}}' \
  | node server.js

または、エージェントに「Direct へのアクセスを確認して」と尋ねるだけです。成功した応答には、ログイン、アカウントの通貨、残りのポイントが表示されます。

私たちが踏んだ落とし穴

別途: トークンをエージェントのチャットに貼り付けてはいけません — 会話履歴に残ります。そのため、save-token.sh は非表示入力になっています。どうしても貼り付けた場合は、id.yandex.ru/personal/data-access でアクセスを取り消し、新しいトークンを取得してください。

ツール

設定

~/.config/yandex-direct/config.json:

{
  "token": "",
  "client_id": "…",
  "client_login": "",
  "sandbox": false
}

トークンは各呼び出し時に読み取られます — 置き換え後もサーバーの再起動は不要です。

トークンの検索順序: YANDEX_DIRECT_TOKEN → config.json → ~/.config/yandex-direct/token。

制限とコスト

各呼び出しはポイント (Units) を消費します。残りは応答ヘッダーに含まれ、結果のヘッダーに表示されます。通常の get は約 10 ポイント、レポートはより高価です。日次制限はアカウントによって異なります (通常のクライアントでは約 160,000、実際の作業には十分な余裕があります)。

get メソッドは一度に最大 10,000 オブジェクトを返します — それ以降は LimitOffset でページングします。入札単価はマイクロ単位で指定します: 30000000 = 30 ₽。レポートの ReportName は一意である必要があります。そうしないと、Direct は以前に生成されたレポートを返します。

連携スキーム

ソース: docs/scheme.html — 申請用に独自の画像バージョンが必要な場合に役立ちます。

ライセンス

MIT — LICENSE を参照。