search-rotation

複数のプロバイダーを利用したウェブ検索とページ抽出のための、1つの MCP サーバーです。

Robin Bially が開発しました。

利用可能なクォータを順に使い、プロバイダーが利用できない場合は自動的に切り替えて、AI アシスタントに一貫した結果を返します。ローカルダッシュボードでは、API キーの管理、エンジンの順序変更、クォータの確認、リクエスト履歴の確認ができます。

実際のダッシュボード UI です。英語で表示され、デモ用のデータを使用しています。呼び出し回数とプロバイダーの予算は別々に表示されます。アクティビティバーでは、期間ごとおよびエンジンごとの詳細を確認できます。

クイックスタート

npm

npx -y search-rotation --http --open

Node.js 20.3+ が必要です。stdio 経由で MCP を使用するには、引数なしで npx -y search-rotation を実行するようクライアントを設定してください。このサーバーは公式 MCP Registry にも io.github.robin-bially/search-rotation として登録されています。

Homebrew

brew install robin-bially/tap/search-rotation
search-rotation --http --open

Homebrew によって、必要な Node.js ランタイムがインストールされます。stdio 経由で MCP を使用するには、引数なしで search-rotation を実行するようクライアントを設定してください。アップグレードや詳細については、Homebrew tap をご覧ください。

GitHub の固定リリース

npx -y --allow-git=all github:robin-bially/search-rotation-mcp#v0.5.2

現在の npm リリースではなく、特定のバージョンを固定して使用したい場合に選んでください。

ダッシュボードでプロバイダーのキーを追加してから、Codex、Claude、Cursor、または OpenCode 用の MCP クライアント設定ガイド に従ってアシスタントを接続してください。

利用できる機能

• 検索と取得： ウェブ検索と Markdown ページ抽出を個別にローテーションします。
• 自動フェイルオーバー： クォータを考慮した順序、レート制限時のクールダウン、リクエストのタイムアウトに対応します。
• ローカルダッシュボード： API キー、ドラッグ＆ドロップによるエンジンの順序変更、エンジンごとの呼び出し回数とエラー、個別のクォータ残高、インタラクティブなリクエスト履歴を管理できます。
• ローカルまたはリモート： stdio または認証済みの Streamable HTTP 経由で MCP を使用できます。

プロバイダー： Tavily · Firecrawl · Parallel · Exa · Google PSE · Jina Reader · DuckDuckGo HTML。キーなしでのアクセスとクォータの計算方法はプロバイダーによって異なります。

MCP ツール

search_web · fetch_url · get_engine_status · update_engine_config · open_dashboard

各名前は、アクションと対象を組み合わせたものです。update_engine_config では、ダッシュボードのエンジン一覧と同じ操作を行えます。エンジンの有効化と無効化、検索および取得のローテーション順序の設定、エンジンごとの月間または日次上限の設定が可能です。API キーはダッシュボードで管理します。クライアントでツール名の許可リストを管理している場合は、以前の web_search と engine_status の項目を置き換えてください。

ダッシュボードの MCP Tools タブでは、各ツールとそのパラメーター、およびコピーして使える呼び出し例を確認できます。

実際のダッシュボード UI です。英語で表示されています。

検索の時間フィルター

search_web は以下の引数を受け付けます。

パラメーター	意味
query	必須の検索テキストです。
numResults	任意の結果数です。1～20を指定します。指定しない場合はダッシュボードの設定が適用されます。
engine	優先するプロバイダーです。時間フィルターへの対応状況と利用可能性に応じて選択されます。フェイルオーバーは引き続き有効です。
timeRange	day、week、month、または year：UTC の日付範囲です。今日までの過去1、7、30、または365日が対象です。
startDate	任意の開始日です。YYYY-MM-DD 形式で指定します。
endDate	任意の終了日です。YYYY-MM-DD 形式で指定します。

timeRange または明示的な日付のいずれかを使用してください。開始日または終了日の片方のみの指定や、開始日と終了日に同じ日付を指定することもできます。無効な日付、開始日が終了日より後の日付、および相対フィルターと明示的なフィルターの併用は、プロバイダーへのリクエスト前に拒否されます。

{"name":"search_web","arguments":{"query":"AI inference research","timeRange":"week","numResults":5}}

{"name":"search_web","arguments":{"query":"AI inference research","startDate":"2026-08-01","endDate":"2026-08-31"}}

相対的な期間は、フェイルオーバー時も含め、リクエストごとに一度だけ UTC の日付に変換されます。これらは日付フィルターであり、厳密な過去24時間のローリング期間ではありません。month と year は暦上の月や年ではなく、それぞれ30日と365日を意味します。Exa には、最初の UTC 日の開始時刻と最後の UTC 日の終了時刻が渡されます。

プロバイダーの対応状況とローテーション

プロバイダー／アクセス方法	相対的な期間	2つの日付境界	1つの日付境界
Tavily、キーの有無を問わない	対応	対応	対応
Firecrawl、キーの有無を問わない	対応	対応	スキップ
Exa、キーを使用した直接 API	対応	対応	対応
Exa、キーなしのホスト型 MCP	スキップ	スキップ	スキップ
Parallel、いずれのアクセス方法でも	スキップ	スキップ	スキップ
Google PSE／DuckDuckGo HTML	スキップ	スキップ	スキップ

この表は、すべての上流機能ではなく、search-rotation で実装されている対応状況を示しています。Tavily には start_date／end_date が渡され、Firecrawl にはカスタムの tbs 範囲が渡され、Exa には startPublishedDate／endPublishedDate が渡されます。Firecrawl は片方の日付のみの指定では慎重を期して対象外となります。その他のスキップ対象の経路には、実装済みの日付マッピングがありません。

ルーターは、互換性のないプロバイダーをクォータチェックとローテーションの前に除外します。互換性のない engine が優先されている場合も同様です。適格なプロバイダープールごとに独自のローテーションカーソルがあるため、フィルター付き検索とフィルターなし検索を混在させても、プロバイダーが利用されなくなることはありません。既存のクォータ優先度、クールダウン、厳格な無料利用ルール、フェイルオーバーは、そのプール内で適用されます。互換性のあるプロバイダーが利用できない場合、検索は明示的に失敗し、フィルターを外して再試行することはありません。時間引数を指定しない検索では、その他の条件を満たすすべてのプロバイダーを引き続き利用できます。

結果にはアダプターから提供された公開日が表示され、リクエスト履歴には指定された期間が含まれます。プロバイダーの日付メタデータは推定値の場合や、存在しない場合があります。Tavily は公開日または更新日で絞り込み、Exa は推定公開日で絞り込み、Firecrawl は検索インデックス独自の日付解釈を使用します。境界を含むかどうかはプロバイダーによって異なります。各ページの公開日を独自に検証するものではありません。Tavily、Firecrawl、Exa のリファレンスを参照してください。

更新後、新しいツールスキーマを読み込むために、MCP クライアントを再接続してください。

リリース

VERSION=0.4.10 ./scripts/release.sh --publish

このスクリプトはパッケージを検証し（npm ci、ビルド、テスト、npm run smoke:package）、バージョンを更新し、ドキュメント内のバージョン指定をそのバージョンに合わせ、コミットとタグ付けを行い、チェックサム付きの tarball をパッケージ化して GitHub リリースを作成し、robin-bially/homebrew-tap のフォーミュラを更新してから、npm レジストリで新しいバージョンが提供されるまで待機します。--publish を指定しない場合は、.build/releases にアーティファクトを準備するだけです。--dry-run は前提条件を確認し、--draft はドラフトリリースを作成し、--force は作業ツリーに未コミットの変更があっても処理を続行します。TAP_DIR が設定されていない場合、tap は一時的にクローンされるため、新規チェックアウトだけで十分です。

npm への公開は、GitHub リリースが公開されると、信頼された公開を通じて .github/workflows/publish.yml で行われるため、スクリプト自体に npm の認証情報は必要ありません。このワークフローを利用するには、npmjs.com で search-rotation の信頼されたパブリッシャーを設定し、このリポジトリと publish.yml を指定する必要があります。

同じワークフローは、server.json から公式 MCP レジストリにもバージョンを登録します。配布と掲載先では、すべての配布経路、それぞれの管理者、各経路で残っている作業を確認できます。

詳細情報

クライアントの設定 · 運用と設定（DE） · 配布と掲載先 · リリース · CI · MIT ライセンス