Searchfetch - Mcp Server For Web Search And Fetching

SearchFetch

AI エージェントに、ステルスブラウザーを通じたウェブ検索とページ取得を提供する MCP サーバーです。ページは JavaScript を実行してレンダリングされ、ノイズを除去したうえで、簡潔な Markdown として返されます。

• ブラウザーによるレンダリング： CloakBrowser は、人間らしい入力を使って Chromium を実行します。取得のたびに、分離されたブラウザーコンテキストを使用します。サイトによっては、引き続きログインやチャレンジが求められることがあります。
• 障害耐性： 接続が切れたブラウザーを再起動し、タイムアウト、ネットワーク障害、HTTP 429 が発生した場合は、Retry-After を尊重し、最大 30 秒で一度だけ再試行します。組み込みの検索エンジンは、DuckDuckGo HTML、さらに DuckDuckGo Lite にフォールバックします。
• トークン効率の高い出力： 変換前に、スクリプト、スタイル、SVG、インラインスタイル、埋め込み data: 画像を削除します。画像、メディア、フォントはネットワーク層でブロックされます。
• テンプレート駆動の抽出： GitHub、GitLab、npm、PyPI、crates.io、docs.rs、Docker Hub、Wikipedia、MDN、Reddit、YouTube、DEV、pkg.go.dev、Javadoc、一般的なドキュメントサイト向けの JSON テンプレートがあります。カスタムテンプレートをインラインで渡すこともできます。
• 2 つのランタイム： Python（uvx、Python 3.11.5 以降）または Node.js（npx、Node 24 以降）を使用でき、ツール、テンプレート、出力は共通です。初回実行時にブラウザーバイナリがダウンロードされます。

セットアップ

手動でインストールする必要はありません。MCP クライアントで uvx または npx を指定してください。

{
  "mcpServers": {
    "searchfetch": {
      "command": "uvx",
      "args": ["searchfetch"]
    }
  }
}

Node.js の場合は、"command": "npx", "args": ["-y", "searchfetch"] を使用してください。Cursor では、uvx searchfetch または npx -y searchfetch を指定した command サーバーを追加します。

ツール

どちらのツールも読み取り専用です。エラーは MCP ツールエラーとして返されます。

websearch

パラメーター	型	デフォルト	説明
query	string	必須	検索クエリ（空白のみは不可）。
engine	string	"duckduckgo"	"duckduckgo"、"google"、検索テンプレート名、またはインライン JSON テンプレート。
region	string/null	null	"us-en" のような地域と言語のコード。DuckDuckGo：kl、Google：gl と hl。
safe_search	boolean/null	null	true または false はエンジンのセーフサーチを設定し、null はエンジンのデフォルトを使用します。
max_results	integer	10	結果の最大数（正の値）。
block_media	boolean	true	画像、メディア、フォントをネットワーク層でブロックします。

結果は、タイトル、URL、スニペットを番号付きリストで表示します。エンジンが失敗した場合、または結果がない場合は、fallback チェーンの次のテンプレート（google → duckduckgo-search → duckduckgo-lite-search）が試され、出力の先頭に表示される [websearch: …] の注記で理由が説明されます。

webfetch

パラメーター	型	デフォルト	説明
url	string	必須	絶対 http/https URL。
template	string	"auto"	"auto"（URL から検出）、テンプレート名、またはインライン JSON テンプレート。
start_index	integer	0	Unicode コードポイント単位の開始オフセット（0 以上）。
max_length	integer	10000	返すコードポイントの最大数（正の値）。
block_media	boolean	true	ネットワーク層で画像、メディア、フォントをブロックします。

出力の末尾には、テンプレート名と文字範囲を示すフッターが付きます。残りのコンテンツがある場合は、次の start_index も示されます。どのテンプレートにも一致しないページは、ナビゲーション、ヘッダー、フッター、サイドバー、ダイアログ、メディアを削除してから、ページ全体を変換します（template="auto (fallback)"）。 raw テンプレートでは、削除を行わずに <body> 全体を変換します。

テンプレート

組み込みテンプレートは templates/ にあり、両方のランタイムで共有されます。ページ テンプレート：github-repo、github-issue、npm-package、pypi-package、crates-package、 docs-rs、javadoc、docs-page、docker-hub、wikipedia、gitlab、reddit、 mdn-web-docs、devto、go-pkg、youtube、raw。検索テンプレート：google-search、 duckduckgo-search、duckduckgo-lite-search。

テンプレートは、読み込み時またはインラインで渡されたときに検証されます。

フィールド	説明
name	必須の一意な名前（インラインテンプレートのデフォルトは "custom" です）。
sections	必須のセクションリスト（下記を参照）。
order	auto 検出での優先順位。値が小さいほど優先されます。
url_patterns	auto 用のテンプレートを選択する正規表現（JavaScript および Python と互換性があります）。
remove	抽出前に削除する CSS セレクター。デフォルトでは、スクリプト、スタイル、SVG、ナビゲーション、フッター、iframe が対象です。
source_url	最初に試す生の Markdown ソース（例："{url}.md"）。HTML のレスポンスは無視されます。
cookies	ブラウザーコンテキストに追加する Playwright Cookie。
block_resources	block_media が有効な場合にブロックするリソースタイプ。デフォルト：image、media、font。
url_template	{placeholders} を含む検索 URL。これにより、テンプレートを websearch で使用できます。
url_params	プレースホルダーごとの設定：required、default、encode: "url"。
engine	"duckduckgo" または "google"：region と safe_search を URL パラメーターにどう対応させるかを指定します。
fallback	このテンプレートが失敗した場合に試す検索テンプレート名。

各セクションには、name、selector（空の場合は <body> を選択）、および任意で format（text、markdown、 attribute と attribute、または html）、transform（strip、 decode_google_url、decode_ddg_url、json_parse、resolve_href のいずれか、またはリスト）、required、multiple、 max_items、children（一致した各要素の内部から抽出するフィールド）を指定します。

トップレベルのカンマで区切られたセレクターは、優先順位付きのフォールバックです。最初に一致したセレクターが使われ、空のフォールバックは現在の要素を選択します。子要素は親要素とその祖先の内部を検索し、隣接する結果は検索しないため、見つからないフィールドは欠落したままになります。必須のセクションまたはフィールドが見つからない場合は、エラーとして報告されます。

最初の項目に Author／User と Comment／Body フィールドがあるレコードセクションはコメントスレッドとしてレンダリングされます。それ以外のレコードは、インデントされた Key: value ブロックとしてレンダリングされます。

開発

npm ci && uv sync --locked --extra dev
git config core.hooksPath .githooks   # optional: format, lint and unit tests before commits

npm test               # Node (node:test) and Python (pytest) unit tests
npm run lint           # ESLint and Ruff
npm run format         # Prettier and Ruff format (format:check to verify)
npm run e2e            # real browser against local fixtures, plus the packed npm and wheel builds
npm run check          # everything CI runs
npm run inspect:node   # MCP Inspector (inspect:py for Python)

レイアウト

パス	内容
src/	Node.js ランタイム（index.js は searchfetch 実行ファイルです）。
searchfetch/	Python パッケージ（python -m searchfetch または searchfetch スクリプト）。
templates/	共有テンプレート。npm パッケージと Python wheel に同梱されます。
tests/fixtures/	両ランタイムの抽出結果と出力を同一に保つ共有フィクスチャです。
tests/node, tests/python	単体テスト。
tests/e2e/	ローカル HTTP サーバーに対して stdio 経由で実行する MCP エンドツーエンドテストです。

両ランタイムはモジュールごとに（templates、extract、markdown、compose、 browser、server）対応しています。一方に変更を加える場合は、動作が外部から確認できる ものであれば、共有フィクスチャも用意したうえで、もう一方にも変更を加えてください。

リリース

package.json と pyproject.toml の両方で version を更新し（その後、npm install と uv lock を実行します）、コミットして対応するタグをプッシュします。

git tag -a v4.0.1 -m "v4.0.1" && git push origin main v4.0.1

Publish ワークフローは、タグが両方のバージョンと一致することを確認し、lint と単体テストを実行した後、npm と PyPI に公開し、生成されたリリースノートとともに GitHub Release を作成します。タグの処理を再試行するには、Actions タブからそのタグを指定してワークフローを手動で実行してください。

制限事項

• HTML から Markdown への変換には turndown（Node）と markdownify（Python）を使用します。一般的なコンテンツでは結果は一致しますが、テーブルなどの特殊なケースでは異なります。
• DOM の準備が整った後、各 fetch はネットワークの動きが落ち着くまで最大 5 秒待機します。その後もレンダリングが続くページでは、コンテンツが一部しか返されないことがあります。
• E2E テストではローカルのフィクスチャを使用します。検索エンジンの稼働状況やサードパーティのページレイアウトは時間とともに変化するため、別途ライブチェックが必要です。