WebSearch MCP Server

websearch-mcpserver

軽量な Web Search MCP Server — API Key 不要ですぐに実行

英語 · 中国語

Go で記述された MCP 検索サービスです。百度ウェブ検索、Bing、DuckDuckGo などの汎用エンジン、Parallel / AnySearch / Exa / Firecrawl の 4 つの API Key 不要のホスト型 MCP アップストリーム、9 つの学術エンジンを内蔵しています。検索、スコアリング、キャッシュはすべてローカルで実行されます。MCP ツールとして Claude Code、Qwen Code、Cursor に接続できるほか、Go モジュールとして独自のサービスに組み込むこともできます。

無料で、中国国内からも利用でき、結果をそのまま LLM で利用できます。 Key がなくても検索でき、Key がある場合は Key を使用します。

---

アーキテクチャの概要

階層化設計により、クライアントが扱う MCP ツールは最大 5 つです。エンジングループは mode で構成され、スコアリング、キャッシュ、プロキシ、取得はすべて同一プロセス内で完結します。クエリがサードパーティの集約サービスを経由することはありません。

層	役割
接続	Claude Code / Qwen Code / Cursor / HTTP API / Go モジュールへの組み込み
プロトコル	/mcp 最大 5 つのツール · /searxng/search LiteLLM 互換 · /__admin プロセス管理 · /dashboard オプションのローカルコンソール · /metrics Prometheus 監視
オーケストレーション	factory / mode による構成 · hybrid / apipool / mcphub · enhance（RRF / Boost / MMR）
エンジン	汎用：百度ウェブ検索 / 千帆 / Bing / DDG / Tavily / Exa / AnySearch / 豆包 / 元宝 / TinyFish / Keenable + 4 つのホスト型 MCP アップストリーム；学術系は 9 ソースを並列実行
サポート	SQLite キャッシュ、システムプロキシの自動検出、webfetch（SSRF 防御）、MinerU、LLM ストリーミング要約、Everything

より詳細なフォールバックチェーン、プロキシ検出、組み込み方法については、docs/architecture.md を参照してください。

---

LLM 向けツールチェーン

5 つの検索ツールが連携します。保存された長時間検索の結果や Web ページ／PDF の本文は、cleanfetch で分割して読み戻せるため、クライアントからコンテナ内のファイルにアクセスする必要はありません。offset=0 から読み取りを開始し、eof=true になるまで next_offset を使って続けて読み取ります。

---

主な機能

機能	説明
API Key 不要の検索	mcphub を推奨します。Parallel / AnySearch / Exa / Firecrawl のホスト型 MCP を順次利用し、失敗後はクールダウンを経て切り替えるため、API Key は不要です。engine モードでは百度ウェブ検索 + Bing などのローカルエンジンを使用します
複数エンジンの融合	複数の検索モード、9 つの汎用エンジン + 4 つのホスト型 MCP アップストリーム + 9 つの学術エンジンを利用し、メインエンジンが失敗すると自動的にフォールバックします
関連性スコアリング	RRF による順位融合 + 語彙の一致度 / ドメイン品質 / 合意度 / 権威性 / 新しさの加点。低スコアの結果は自動的に除外し、MMR で転載／ミラーを分散します
応答の透明性	失敗一覧、日付、検索の出典情報を提供します。リクエストのキャンセルは各エンジンに伝播し、エンジンごとにソフトタイムアウトを設定します。上限を超えた検索では候補のプレビューを保持し、完全な結果をディスクに保存した後、result_ref を提供します。cleanfetch の参照読み取りモードで分割して読み取れます
学術検索	9 つの学術エンジンを並列実行し、引用数 / ジャーナルの権威性 / PDF の利用可能性 / 新しさでスコアリングします。DOI を使ってエンジン間の重複を排除します
Web ページの取得	cleanfetch に SSRF / DNS rebinding 防御と巨大ファイルの事前検査を内蔵し、失敗時は Jina Reader にフォールバックします。オプションの fetch_mode ではホスト型 MCP の取得機能を再利用できます
PDF 解析	まずローカルで PDF テキストを抽出し、スキャン文書の場合は MinerU OCR にフォールバックできます。リモート MinerU は画像を含む ZIP の URL を返します。元ファイルが 1 タスクあたりの上限（デフォルト 600 ページ）を超える場合、ローカル qpdf で選択したページを切り出します。自動分割と 1 回あたりのページ数予算を設定すると、分割してアップロードできます。MinerU の待機時間は調整可能です。タイムアウト後も状態とタスク参照を保持し、元のタスクを引き続き確認できます
LLM 要約	オプションで OpenAI 互換 API に接続して構造化要約を生成でき、ストリーミング配信にも対応します
システムプロキシ	Clash などでシステムプロキシを有効にすると、海外エンジン / Jina Reader は自動的にプロキシを経由します
ローカルファイル検索	file_search は Everything のインデックスを使ってローカルファイルをミリ秒単位で特定します。ディレクトリの許可リストで範囲外へのアクセスを防ぎ、語彙の一致度による二次フィルタリングでコンテキストの過剰な増加を防ぎます（Everything HTTP Server が必要です）
ローカルコンソール	オプションで dashboard.enabled を設定できます。/dashboard/ は読み取り専用の監視画面です。呼び出し統計、ソースの健全性、失敗分類、許可リスト設定の変更、Prometheus 形式の GET /metrics を提供します（デフォルトでは無効です）
軽量なデプロイ	単一バイナリ、CGO 不要、参照カウント方式のプロセス管理。Go モジュールとして組み込めます
中国語 / 英語	`language: auto

---

検索とスコアリングのパイプライン

結果は単純な集約ではありません。複数エンジンからの応答をローカルで重複排除し、順位を融合して多様性を考慮した並べ替えを行い、必要に応じて要約を生成します。

---

背景と設計目標

既存の MCP 検索ソリューションには、それぞれ課題があります。ベンダーのサービス（Tavily / Exa など）は Key が必要で従量課金制であり、データがサードパーティを経由し、中国国内からのアクセスが不安定です。SearXNG のセルフホストには Python サービスの保守が必要で、結果は最適化されていない単純な集約です。このプロジェクトでは、こうした機能をローカルに集約します。単一バイナリに複数エンジンの融合、9 つの学術ソース、Web ページ取得、PDF 解析を組み込み、検索を LLM 向けの無料で、中国国内からも利用でき、結果をそのまま消費できる基盤機能にします。

プロジェクト立ち上げの動機、既存ソリューションとの観点別比較、設計原則（プライバシーを重視したローカル優先 / ゼロコストで開始 / 必要に応じて機能を拡張 / 疎結合で組み合わせ可能 / LLM 向けの完全なツールチェーン / 用途に合わせた最適化）の詳細については、docs/design.md を参照してください。

---

クイックスタート

# 1. 下载二进制: https://github.com/daidaiJ/websearch-mcpserver/releases
# 2. 启动（无需手写配置，无需 API Key）
# Windows 开机自启动 可选
./websearch-mcpserver.exe install
#
#    首次 install 会在可执行文件目录自动生成一份可编辑的预设 config.yaml 和 autostart.vbs
./websearch-mcpserver start
# 或者点击
autostart.vbs
# 3. 注册到 MCP 客户端（见 docs/installation.md）

「ゼロ設定」とは、初回起動時に config.example.yaml と同じプリセットの config.yaml を自動生成することです。ポート／Key／モードの変更はすべてこのファイルで行います。デフォルトでは 127.0.0.1 のみをリッスンします。ネットワークインターフェースに公開する（host: 0.0.0.0）場合は、業務エンドポイントを保護するために auth_token を設定することをおすすめします。

Key 不要で MCP カスケードを利用するには、このファイルの mode を mcphub に変更するだけです（mcp_hub.enabled はデフォルトで有効です）。

または、MCP Hooks を使ってセッションを自動で開始／停止することもできます（Qwen Code の例です。詳しくは docs/installation.md をご覧ください）。

{
  "hooks": {
    "SessionStart": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "/path/to/websearch-mcpserver start", "timeout": 10000 }] }],
    "SessionEnd":   [{ "matcher": "*", "hooks": [{ "type": "command", "command": "/path/to/websearch-mcpserver stop",  "timeout": 10000 }] }]
  }
}

---

検索モードの概要

mode の1つのフィールドでエンジンの組み合わせが決まります。Key 不要の場合は mcphub がおすすめです（MCP カスケードを管理し、失敗時のクールダウンとローカルエンジン／Bing へのフォールバックに対応）。API Key がある場合は apipool がおすすめです（複数プロバイダーの Key プールをローテーションし、失敗時は自動で切り替え、ウェブエンジンをフォールバックとして使用します）。engine はローカルウェブエンジンだけを使い、MCP を必要としない場合に適しています。baidu／tavily／exa／anysearch／doubao／yuanbao は単一プロバイダーへの直接接続です（Key がある場合のみ参加し、メインエンジンの失敗時は自動でフォールバックします）。hybrid は全エンジンを並列で実行します。mcphub では rotation_engines でローカルエンジンをローテーションに追加でき、プロキシの利用可否に応じて、プロキシが必要な上流を自動で有効化／スキップします。Key がない場合、単一プロバイダーモードは自動的に engine にフォールバックします。

各モードの参加エンジン、Key の取得先、sk_list による複数 Key のローテーション、エンジンごとのレート制限については docs/search.md をご覧ください。

mcphub に組み込まれている4つのプリセット：

preset	デフォルトでプロキシが必要	特徴
parallel	いいえ	直接接続で利用でき、遅延が最も低い
anysearch	いいえ	中国国内からの直接接続に適し、中国語の検索結果が安定
exa	はい	匿名利用時のレート制限が比較的緩い
firecrawl	はい	匿名利用のクォータは出口 IP ごとに割り当て

• カスケード順序はデフォルトで parallel → anysearch → exa → firecrawl です。1回のリクエストで使用されるのは1つで、失敗すると60秒間クールダウンしてから切り替わります。これはルーティングとフォールバックであり、複数サービスの結果をまとめて返すものではありません。
• すべて失敗した場合は、fallback_engines（デフォルトは bing → so360。有効になっていないエンジンは自動でスキップされ、so360 はデフォルトで無効）にフォールバックし、最終的には smartsearch が Bing にフォールバックします。
• 各上流には api_key／sk_list を設定できます。空欄の場合は匿名プランが使われます。認証に失敗すると自動で次の Key に切り替わり、接続エラー／タイムアウトの場合は該当 server をクールダウンしてカスケードを続行します。exa／firecrawl はプロキシが検出された場合のみローテーションに参加し、プロキシが復旧すると自動で再参加します。
• rotation_engines を使うと、ローカルエンジン（so360 など）をメインローテーションに加え、匿名利用時のレート制限を分散できます。
• fetch_mode: off / fallback / prefer を使うと、cleanfetch で同じ MCP 取得処理を再利用できます（mode=mcphub の場合、検索 Hub のクールダウンと Key プールを共有します）。PDF は引き続きローカルで解析され、SSRF／HEAD の事前チェックは省略されません。

---

ローカルコントロールセンター（オプション、デフォルトでは無効）

dashboard.enabled: true に設定すると、ローカルブラウザーから http://127.0.0.1:8338/dashboard/ にアクセスできます。ページは4つあります。KPI の概要とクライアント使用量のグループ化、検索ソースの健全性と失敗の内訳、リクエスト単位の呼び出しチェーン（絞り込みと CSV エクスポートが可能）、バックアップ後に書き込み可能なホワイトリスト設定です。全体を通して受動的に監視し、失敗の分類は報告のみで、呼び出しには介入しません。

有効にすると、dashboard.example.yaml が config.yaml と同じディレクトリの dashboard.yaml にコピーされます（初回の start／install 時に自動生成され、デフォルトで有効です。ランダムなローカル管理者パスワードが含まれます）。このファイルを削除して再起動すれば、完全に元の状態に戻り、実行時のテレメトリー負荷もゼロです。デフォルトのプライバシー設定では、クエリはハッシュとトピックなどの秘匿化されたメタデータのみを保存し、キーとクエリの原文はデータベースに保存されず、API が返すこともありません。デフォルトではローカルの loopback からのみ読み取り可能で、書き込み操作には admin_password が必要です。さらに GET /metrics も提供します（Prometheus/OpenMetrics 形式のテキストで、読み取り専用、秘匿化された集計情報のみ）。利用には dashboard.enabled: true が必要で、無効の場合は 503 を返します。

ページの詳細、すべての設定キー、ショートカットの配置場所、セキュリティモデル、呼び出し元の判定については docs/dashboard.md をご覧ください。

---

ドキュメント案内

各ドキュメントは中国語がデフォルトで、同名の .en.md が英語版です。

読者	ドキュメント	内容
👤 人間のユーザー	docs/HUMAN_GUIDE.md	人間向けガイド：ドキュメントの読み方、モードの選択、チューニング手順、トラブルシューティング早見表
🤖 AI エージェント	docs/AGENT_GUIDE.md	トークン節約版：デプロイ早見表、ツールパラメーター早見表、機械向け契約、エラーの迅速な診断
📚 参考	docs/installation.md	インストールとデプロイ（バイナリ：4プラットフォーム／GHCR linux amd64+arm64／ソースコード／クライアント登録）、運用とトラブルシューティング
📚 参考	docs/configuration.md	設定の完全なリファレンス、環境変数による上書き、デフォルト値の早見表
📚 参考	docs/search.md	検索モードの詳細、エンジンの比較、関連性スコア、MCP ツールのパラメーター
📚 参考	docs/architecture.md	アーキテクチャ設計、フォールバックチェーン、プロキシ検出、キャッシュ、Go モジュールへの組み込み、web-researcher の拡張
📚 参考	docs/design.md	設計の背景と目標：プロジェクト立ち上げの動機、既存ソリューションとの比較、設計原則
📚 参考	docs/api.md	Go Module API と HTTP API（MCP／SearXNG／Admin エンドポイント）
📚 参考	docs/dashboard.md	ローカルコントロールセンター：すべての設定キー、書き込み操作のセキュリティモデル、プライバシーの境界
📚 参考	docs/developers.md	開発者ガイド：パッケージ構成、インターフェース契約、ツール呼び出しチェーン、変更箇所
📚 参考	CHANGELOG.md	バージョン変更履歴

関連プロジェクト

• web-researcher — Qwen Code 用の連携拡張機能です。ウェブ調査をサブエージェントに委譲し、メインモデルのコンテキストを整理された状態に保ちます（詳しくは docs/architecture.md をご覧ください）