Yandex Wordstat MCP

yandex-wordstat-mcp

Yandex Cloud Search API v2 経由で Yandex Wordstat を利用する MCP サーバーです。キーワードを調査し、検索ボリュームの傾向を分析し、ロシアおよび CIS 市場における地域別の検索分布を確認できます。

v2.0： 従来の api.wordstat.yandex.net API は、Yandex により 2026 年に停止されました。このサーバーは現在、searchapi.api.cloud.yandex.net/v2/wordstat/* と通信し、OAuth トークンではなく Yandex Cloud API キーで認証します。ツール名とパラメーターに変更はありません。

インストール

このパッケージは @stufently/yandex-wordstat-mcp として公開されています。スコープなしの名前 yandex-wordstat-mcp は、無関係な公開元が所有しています（ルート README の注記を参照してください）。 スコープにはまだパッケージがないため、ソースから実行してください。

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

設定

MCP クライアントの設定に追加してください。

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "node",
      "args": ["/path/to/yandex-mcp/packages/yandex-wordstat-mcp/src/index.mjs"],
      "env": {
        "WORDSTAT_API_KEY": "AQVN...",
        "WORDSTAT_FOLDER_ID": "b1g..."
      }
    }
  }
}

または、認証情報を ~/.config/yandex-cloud/wordstat.env に設定してください（環境変数が設定されていない場合のフォールバックとして使用されます）。

WORDSTAT_API_KEY=AQVN...
WORDSTAT_FOLDER_ID=b1g...

環境変数

変数	必須	説明
WORDSTAT_API_KEY	はい	サービスアカウントの Yandex Cloud API キー（シークレット、AQVN...）
WORDSTAT_FOLDER_ID	はい	請求とアクセス確認に使用する Yandex Cloud フォルダー ID（b1g...）

認証（キーの取得方法）

1. Yandex Cloud コンソールにサインインし、フォルダーを選択（または作成）します。フォルダー ID は URL console.yandex.cloud/folders/<folderId>/... で確認できます。クラウドには請求アカウントをリンクする必要があります。
2. そのフォルダーに、search-api.webSearch.user ロールを持つ サービスアカウント を作成します。
3. サービスアカウントを開き、新しいキーを作成 → API キーを選択し、スコープを yc.search-api.execute に設定します。
4. シークレット（一度だけ表示されます）を WORDSTAT_API_KEY にコピーします。キー識別子（ajel...）は、後でキーをローテーションまたは失効させる場合にのみ必要です。

レート制限

サーバーはスライディングウィンドウを使用して、クライアント側で 1 秒あたり 10 リクエストのレート制限を適用します。制限を超えたリクエストは自動的にキューに追加されます。また、429 および 5xx のレスポンスが返された場合は、指数バックオフで自動的に再試行します。

ツールリファレンス

get-regions-tree

Yandex Wordstat の地域階層ツリーを取得します。

パラメーター	型	必須	デフォルト	説明
depth	number	いいえ	3	ツリーの最大深度（1～5）

value（地域 ID）、label（名前）、children を含む地域ツリーを返します。

get-region-children

キャッシュされたツリーから、指定した地域の子地域を取得します。API 呼び出しは行わず、キャッシュされた地域ツリーを使用します。

パラメーター	型	必須	デフォルト	説明
regionId	number	はい	--	子地域を取得する地域 ID
depth	number	いいえ	2	サブツリーの最大深度（1～3）

top-requests

キーワードを含む人気の検索クエリ（直近 30 日間）と、関連クエリを検索します。

パラメーター	型	必須	デフォルト	説明
phrase	string	はい	--	検索するキーワードまたはフレーズ（最大 400 文字）
regions	number[]	いいえ	--	絞り込み対象の地域 ID
devices	enum[]	いいえ	--	デバイスの種類：desktop、phone、tablet
limit	number	いいえ	100	レスポンスに含めるフレーズの最大数（1～2000）

検索ボリューム順に並んだ { topRequests: [{ phrase, count }], associations: [{ phrase, count }], totalCount } を返します。

dynamics

キーワードの検索ボリュームの経時的な傾向を分析します。

パラメーター	型	必須	デフォルト	説明
phrase	string	はい	--	キーワードまたはフレーズ（最大400文字）
period	enum	いいえ	monthly	集計単位：daily、weekly、monthly
fromDate	string	いいえ	auto	開始日（YYYY-MM-DD）
toDate	string	いいえ	auto	終了日（YYYY-MM-DD）
regions	number[]	いいえ	--	地域 ID
devices	enum[]	いいえ	--	デバイスの種類：desktop、phone、tablet

API には、どこにも文書化されていない期間のルールがあり、違反すると未加工の gRPC エラーが返されます（2026-07-29 に実 API で確認済み）。

期間	ルール
daily	fromDate は過去60日以内である必要があります。ちょうど60日前は拒否されます
weekly	fromDate は月曜日、toDate は日曜日である必要があり、該当する週が終了している必要があります
monthly	fromDate は月の1日、toDate は月の最終日である必要があり、該当する月が終了している必要があります

指定した日付は拒否されず、最も近い有効な期間に調整されます。調整内容はすべて、テキストの概要と structuredContent の両方の adjustments に一覧表示されます。1週間または1か月の途中に収まる範囲は、その期間全体に拡張されます。現在進行中で終了していない週または月のみを対象とする範囲には対応できず、API に拒否されるため、ツールは400エラーを転送する代わりに、その旨と利用可能な最新の toDate を伝えます。

期間ごとのデフォルトの日付範囲：

• daily：過去58日間（UTC の日付が切り替わってもリクエストが期限切れにならないよう、制限より1日分内側に設定）
• weekly：過去52週分の完了した週（月曜日から日曜日）
• monthly：過去12か月分の完了した月（月初から月末）

日付の計算はすべて UTC で行われます。

{ date, count, share } データポイントの配列を返します。

regions

キーワードの検索関心度を地域別に取得します。

パラメーター	型	必須	デフォルト	説明
phrase	string	はい	--	キーワードまたはフレーズ（最大400文字）
regions	number[]	いいえ	--	絞り込み対象の地域 ID（クライアント側で適用され、子孫地域を含みます）
devices	enum[]	いいえ	--	デバイスの種類：desktop、phone、tablet
limit	number	いいえ	20	結果の最大件数（1～50）

{ regionId, regionName, count, share, affinityIndex } の配列を件数順に返します。地域名はキャッシュされた地域ツリーから補完されます。

キャッシュ

地域ツリーは、get-regions-tree、get-region-children、または regions の初回呼び出し時に取得され、サーバーセッション全体でキャッシュされます。地域名を O(1) で解決できるフラットな検索マップが構築されます。

ライセンス

MIT