Skip to main content
Glama
yandex-direct-mcp

yandex-direct-mcp

by iarbor04

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 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 へのアクセスを確認して」と尋ねるだけです。成功した応答には、ログイン、アカウントの通貨、残りのポイントが表示されます。

私たちが踏んだ落とし穴

症状

原因

対処

error 58 — 「未完了の登録」、申請は承認されているのに

トークンが申請が承認されたアプリケーションとは別のアプリケーションで取得された。複数のアプリケーションがあると簡単に遭遇する

承認された申請を開き、Client ID を確認し、そのアプリケーションでトークンを取得する

サンドボックスでの error 58

サンドボックスも承認された申請が必要

承認を待つしかない、回避策はない

再認証で同じトークンが返される

アプリへのアクセスが取り消されるまで、Yandex は既に発行されたトークンを返す

id.yandex.ru/personal/data-access でアクセスを取り消し、再認証する

error 53 — 「無効な OAuth トークン」

トークンが取り消された、期限切れ、または切り詰めてコピーされた

./save-token.sh で再取得する

clients.get は応答するが、campaigns.get が空のリストを返す

トークンがキャンペーンのないログインで発行された

必要なログインでトークンを取得する。再申請は不要: 申請はユーザーではなくアプリケーションに対して承認されている

アプリケーションを再作成した後、申請を再提出する必要がある

承認はアカウントではなく Client ID に紐付いている

承認されたアプリケーションを削除しない。削除した場合は新しい申請を行い、説明に以前の Client ID を記載する

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

ツール

ツール

目的

direct_status

トークンの有無、環境、アクセスが有効か (テスト clients.get)、残りポイント。トークンは開示されない

direct_reference

チートシート: サービス、メソッド、params の例、レポートタイプ、入札単位、制限

direct_call

汎用呼び出し POST /json/v5/{service}、ボディは {method, params}

direct_report

Reports API: ReportDefinition を送信し、準備完了を待ち (コード 201/202)、TSV を返す

設定

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

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

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

環境変数

意味

YANDEX_DIRECT_TOKEN

トークンを直接指定、ファイルより優先

YANDEX_DIRECT_CLIENT_LOGIN

代理店アカウントのクライアントログイン (ヘッダー Client-Login)

YANDEX_DIRECT_SANDBOX=1

サンドボックスを使用する

YANDEX_DIRECT_READONLY=1

add、update、delete、suspend、resume、moderate、set をブロックする

YANDEX_DIRECT_CONFIG_DIR

別の設定ディレクトリ

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

制限とコスト

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

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

連携スキーム

Яндекс Директ API との連携スキーム

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

ライセンス

MIT — LICENSE を参照。

Available Tools

4 tools
direct_callA

Универсальный вызов Яндекс Директ API v5: POST на /json/v5/{service} с телом {method, params}. Покрывает всё управление: кампании, группы, объявления, ключевые фразы, ставки, ретаргетинг, справочники. Сначала загляни в direct_reference за именами сервисов, методов и формой params.

Inputs: method (required), service (required), params, sandbox, +1 more.

direct_referenceA

Шпаргалка по API v5: список сервисов, методов, примеры params, типы отчётов, единицы ставок и лимиты. Вызывай перед первым direct_call, чтобы не гадать с полями.

Inputs: no named parameters.

direct_reportA

Статистика через сервис Reports API v5. Принимает ReportDefinition в params, сам дожидается готовности отчёта (коды 201/202 с повторами) и возвращает TSV.

Inputs: params (required), sandbox, client_login, wait_seconds, +1 more.

direct_statusA

Проверить подключение к Яндекс Директу: найден ли токен, какая среда (боевая/песочница), доступен ли API (пробный clients.get) и сколько осталось баллов. Токен не раскрывается.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool has a clearly distinct role: status check, generic API call, report retrieval, and API reference. There is slight overlap because direct_call could theoretically hit report services or reference data, but the descriptions clearly separate async reports and reference lookups, so an agent can reliably choose the right tool.

    Naming Consistency5/5

    All tools share the 'direct_' prefix followed by a single concise word, creating a highly predictable and consistent naming scheme. The pattern is uniform and avoids mixed conventions or vague generic names.

    Tool Count5/5

    With 4 tools, the server is intentionally compact: a generic API call handles the long tail of operations, while status, report, and reference tools cover cross-cutting concerns. This is a well-scoped count for a broad but unified API surface.

    Completeness5/5

    The generic direct_call provides full coverage of all Yandex Direct API services and methods, so no CRUD operations are missing. direct_report adds proper handling of async report generation, and direct_reference closes the discoverability gap. The set is complete for its stated purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables managing Yandex Direct PPC campaigns, ad groups, ads, and keywords, plus pulling performance statistics via the Yandex Direct API v5.
      46
      920 npm
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables interaction with Yandex advertising and analytics APIs (Direct, Metrika, Audience, Webmaster, AdMetrica) through MCP tools, resources, and prompts for campaign management and data retrieval.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to manage Yandex Direct advertising campaigns, ads, keywords, and reports via natural language using the Yandex Direct API v5.
      2
      1
      MIT