Yandex Search.API MCPサーバー

REST経由でYandex Search APIを利用するための7つのツールを備えたMCPサーバーです：

• web_search

• image_search

• generative_search

• wordstat_get_top

• wordstat_get_dynamics

• wordstat_get_regions_distribution

• wordstat_get_regions_tree

サーバーはMCPクライアントの環境設定から以下の認証情報を読み取ります：

• FOLDER_ID

• API_KEY

ローカル開発環境では、.envファイルが自動的に読み込まれます。

特徴

• RESTエンドポイントのみを使用 (/v2/web/search, /v2/image/search, /v2/gen/search, Wordstat RESTパス)

• モデルのコンテキストをコンパクトに保つため、ツールへの入力を最小限に抑えています

• すべての関連ツールで searchType が利用可能で、デフォルトは SEARCH_TYPE_COM です

• ウェブ検索は常に responseFormat: FORMAT_XML を強制します

• ウェブ/画像ツールはBase64から rawData をデコードし、XMLを構造化されたグループに解析します

• 明確なAPIステータスと詳細を含むエラーハンドリング

インストール

npm install yandex-searchapi-mcp

MCPクライアント設定例

{
  "mcpServers": {
    "yandex-searchapi": {
      "command": "npx",
      "args": ["-y", "yandex-searchapi-mcp"],
      "env": {
        "FOLDER_ID": "your-folder-id",
        "API_KEY": "your-api-key"
      }
    }
  }
}

ツール

web_search

生成された回答ではなく、従来のウェブ検索結果（リンク + スニペット）が必要な場合に使用します。

入力：

• query (必須)

• searchType (オプション、デフォルト SEARCH_TYPE_COM)

• page (オプション)

• docsOnPage (オプション)

• familyMode (オプション)

• fixTypoMode (オプション)

戻り値：

• groups[] (各ドキュメントに以下を含む documents[] を持つ):

  • url

  • title

  • language

  • passages

• requestId

• found

注：ウェブ検索の場合、この入力はアップストリームAPIの groupSpec.groupsOnPage にマッピングされます。

image_search

画像検索結果および画像のメタデータ（サムネイル/オリジナルリンクおよび寸法）が必要な場合に使用します。

入力：

• query (必須)

• searchType (オプション、デフォルト SEARCH_TYPE_COM)

• page (オプション)

• site (オプション)

• docsOnPage (オプション)

• imageSpec (オプション: format, size, orientation, color)

戻り値：

• groups[] (各ドキュメントに以下を含む documents[] を持つ):

  • url

  • extras.image-properties (存在する場合)

• requestId

• found

generative_search

検索結果から統合された、すぐに使える根拠のある回答が必要な場合に使用します。

入力：

• query (必須)

• searchType (オプション、デフォルト SEARCH_TYPE_COM)

• fixMisspell (オプション)

• getPartialResults (オプション)

• scope (オプション): { type: "site" | "host" | "url", values: string[] }

生成されたコアフィールドのみを返します（ラッパーオブジェクトなし）：

• message

• sources

• searchQueries

• fixedMisspellQuery

• isAnswerRejected

• isBulletAnswer

• hints

• problematicAnswer

wordstat_get_top

キーワードに関連してユーザーがどのようなクエリを検索しているかを把握するために使用します。

入力：

• phrase (必須)

• numPhrases (オプション、デフォルト 20)

• regions (オプション)

• devices (オプション)

戻り値：

• totalCount

• results

• associations

wordstat_get_dynamics

キーワードの需要トレンドを時系列で追跡するために使用します。

入力：

• phrase (必須)

• period (オプション、デフォルト PERIOD_WEEKLY)

• fromDate (オプション、デフォルト now-30d, ISO日時)

• toDate (オプション、デフォルト now, ISO日時)

• regions (オプション)

• devices (オプション)

戻り値：

• results

wordstat_get_regions_distribution

キーワードがどの地域/都市で相対的に人気があるかを確認するために使用します。

入力：

• phrase (必須)

• region (オプション、デフォルト REGION_ALL)

• devices (オプション)

戻り値：

• results

wordstat_get_regions_tree

地域別のWordstatフィルターに使用する有効な地域IDと名前を取得するために使用します。

入力：

• なし

戻り値：

• regions

開発

npm install
npm run build
npm run dev