MCP Web Search Tool

MCP Web Search Tool

アシスタントにライブウェブ検索、ページ全体の読み取り、出典の引用機能を提供する MCP サーバーです。Stdio トランスポート、プロバイダーの差し替えに対応し、スクレイパーへの依存はありません。

クイックスタート · ツール · 設定 · クライアント · セキュリティ · 変更履歴

---

概要

5 つのツールを提供します：web_search、news_search、image_search、fetch_url、list_providers。検索結果は、安定した ID 付きの、順位付けされた概要を返します。fetch_url は、任意の ID に対応するページを読み取ります。主なプロバイダーは Brave Search で、キーなしで使えるフォールバックとして DuckDuckGo が動作します。

要件

Node.js	>= 20.18（ネイティブの fetch を使用）
npm	>= 10
Brave Search API キー	任意です。キーがない場合、web_search は DuckDuckGo を使用します。news_search と image_search にはキーが必要です。

クイックスタート

npm から：

npx -y mcp-web-search-tool

MCP クライアントで、引数 ["-y", "mcp-web-search-tool"] を指定した npx を参照し、クライアントの env ブロックを通じて BRAVE_API_KEY を渡します。

ソースから：

git clone https://github.com/gabrimatic/mcp-web-search-tool.git
cd mcp-web-search-tool
npm install
cp .env.example .env   # edit BRAVE_API_KEY if you have one
npm run build
npm start

Docker で実行：

docker build -t mcp-web-search .
docker run --rm -i -e BRAVE_API_KEY mcp-web-search

Claude Desktop、Claude Code、Codex、VS Code、Cursor、Windsurf との連携については、MCP_CLIENTS.md を参照してください。

---

ツール

検索ツールは、信頼できないコンテンツを示すバナー、モデル向けの Markdown 形式の表示、構造化ペイロードを含むフェンス付き JSON ブロックを返します。fetch_url は、読みやすいページ本文とリンクブロックを返します。エラーは、対応方法を示すメッセージを含む isError: true のコンテンツとして返されます。不明なツールの呼び出しのみ、プロトコルエラーがスローされます。

web_search

ライブウェブ検索です。最新の情報を出典に基づいて回答する際に、最初に使用してください。

パラメーター	型	説明
search_term	string、必須	クエリ文字列です。
provider	enum	"brave search" または "duckduckgo" です。キーが設定されている場合は Brave が、それ以外の場合は DuckDuckGo がデフォルトで使用されます。
count	int（1～20）	結果の件数です。デフォルトは 10 です。
offset	int	ページネーションのオフセットです（ウェブ検索のみ）。
cursor	string	前回のレスポンスから取得した不透明なカーソルです。
freshness	string	pd（24 時間）、pw（1 週間）、pm（1 か月）、py（1 年）、または YYYY-MM-DDtoYYYY-MM-DD です。
country	string	ISO 国コードです。
search_lang	string	UI 言語です。例：en。
safesearch	enum	off、moderate、strict です。
include_domains	string[]	結果をこれらのホストに限定します。
exclude_domains	string[]	これらのホストからの結果を除外します（ホスト名のサフィックスで照合）。

news_search

ソース名と公開日を含む、最近のニュースを検索します。Brave のみで利用できます。

image_search

サムネイル付きの画像検索結果を返します。Brave のみで利用できます。

fetch_url

検索結果または任意の http(s) URL を読み取ります。前回の検索結果の ID（推奨）または完全な URL を渡してください。

パラメーター	型	説明
id_or_url	string	結果 ID（例：r_a1b2c3d4e5f6）または完全な http(s) URL です。
url	string	id_or_url の非推奨エイリアスです。
max_chars	int（200～200 000）	返される文字数のソフト上限です。デフォルトは 8000 です。
cursor	string	前回のレスポンスから取得したカーソルで、読み取りを続けます。

ページタイトル、読みやすいテキスト（スクリプト、スタイル、ナビゲーション、フッター、サイドバーは除去）、最初の 25 件の外部リンク、HTTP ステータス、コンテンツタイプ、バイト長、切り捨てが発生した場合は nextCursor を返します。

http(s) 以外のスキームと、プライベート、ループバック、リンクローカル、マルチキャスト、または IPv4 マップ IPv6 のプライベートアドレスに解決されるホストは拒否されます。詳細については、SECURITY.md を参照してください。

list_providers

登録済みのプロバイダーと現在のデフォルトを返します。このセッションで news_search または image_search が利用可能かどうかわからない場合は、一度呼び出してください。

---

設定

すべての設定は環境変数で行います。参考：.env.example。

変数	デフォルト	用途
BRAVE_API_KEY	空	Brave Search API キー。設定されていない場合は DuckDuckGo が使用されます。
MAX_RESULTS	10	デフォルトの結果数（1～50 に制限）。
REQUEST_TIMEOUT	10000	リクエストごとのタイムアウト（ミリ秒、1 000～60 000）。
DEFAULT_PROVIDER	auto	特定のプロバイダーを強制的に指定します（例：duckduckgo）。
ALLOW_KEYLESS	true	false の場合、BRAVE_API_KEY がないとサーバーは起動しません。
CACHE_MAX_ENTRIES / CACHE_TTL_MS	256 / 300000	検索キャッシュ。
FETCH_CACHE_MAX / FETCH_CACHE_TTL_MS	128 / 600000	URL 取得キャッシュ。
FETCH_TIMEOUT_MS / FETCH_MAX_BYTES	15000 / 2000000	fetch_url のリクエストごとの予算。
RESULT_ID_CACHE_MAX / RESULT_ID_TTL_MS	2000 / 3600000	fetch_url が解決できる結果 ID の数と有効期間。

---

プロジェクトの構成

src/
├── index.ts                    MCP server: tool registry, dispatch, rendering
├── config.ts                   env loader, validation, defaults
├── providers/
│   ├── SearchProvider.ts       abstract contract and shared types
│   ├── SearchProviderFactory   registry and default selection
│   ├── BraveSearchProvider     web/news/images via Brave API
│   └── DuckDuckGoProvider      keyless HTML-lite fallback
├── services/
│   ├── SearchService.ts        provider dispatch, LRU+TTL cache
│   └── FetchService.ts         safe URL fetch, readable extraction
└── utils/
    ├── http.ts                 native fetch, retry/backoff/timeout
    ├── html.ts                 zero-dep HTML to text + links
    ├── cache.ts                LRU+TTL cache
    └── ids.ts                  stable result-id minting and resolution
tests/                          vitest suite

プロバイダーの追加

import { SearchProvider, SearchResponse, SearchOptions } from './SearchProvider.js';

export class MyProvider extends SearchProvider {
  getName() { return 'My Provider'; }
  override requiresApiKey() { return true; }
  async search(query: string, _opts: SearchOptions = {}): Promise<SearchResponse> {
    const out = this.emptyResponse(query, 'web');
    out.results = mapped; // shape: SearchResult[]
    return out;
  }
}

SearchProviderFactory.setupDefaults に登録します。各エントリーで mintResultId(url) を呼び出すと、結果 ID が自動的に生成されます。

---

開発

npm run dev          # tsx watch mode
npm test             # vitest suite
npm run lint         # eslint + prettier
npm run typecheck    # tsc --noEmit
npm run format
npm run build

CI では Node 22 と 24 で lint、format check、type check、build、tests を実行します。イメージの入力に変更があった場合は、Docker イメージをビルドします。テストでは、LRU+TTL キャッシュ、HTML 抽出器、DuckDuckGo パーサー、検索サービスのキャッシュ、HTTP のリトライ／バックオフ、SSRF ガード、ドメイン照合、結果 ID リゾルバーを対象としています。

---

プロンプトの例

• 「今夜の NBA の試合を受けて、MVP レースについてアナリストは何と言っていますか？」
• 「RAG benchmarks 2025 の上位 3 件の結果を要約し、最初の論文の要旨を取得してください。」
• 「Webb 望遠鏡の最新のディープフィールドの画像を探し、NASA のページを開いてキャプションを引用してください。」
• 「現在のベルリンの天気はどうですか？」

---

ライセンス

MIT ライセンス

開発者

Soroush Yousefpour による開発

© All rights reserved.

YouTube 動画

Claude を使った MCP Web Search Tool の短いデモ：

Claude + MCP Web Search – ライブデモ

Medium の記事

プロジェクトの背景と仕組みについて：

MCP Web Search Tool を詳しく解説

サポート