web-to-markdown-mcp

web-to-markdown-mcp

URL を取得し、主要なコンテンツを整形された Markdown として返す MCP サーバーです。可能な場合は通常の HTTP を使用し、必要に応じて実際の Chromium を使用します。

理由

多くの MCP ウェブ取得ツールには、次のような問題があります。

• 通常の HTTP を使用するため、JavaScript が必要なページでは失敗し、多くのサイトで Cloudflare のボット検出にブロックされます。または
• 実際のブラウザーを使用しますが、記事を読むだけの場合でも、ノイズが多くトークンを大量に消費する生の HTML やアクセシビリティツリーのスナップショットを返します。

このサーバーは 3 段階の方式を採用し、URL ごとに動作する最速の方法を使用します。

1. ネイティブ Markdown の高速処理。 すべてのリクエストで、まず Accept: text/markdown ヘッダーを付けた通常の HTTP GET を試します。Cloudflare がホストするサイトで Markdown for Agents が有効になっている場合など、コンテントネゴシエーションに対応するサーバーは Content-Type: text/markdown で応答し、ブラウザーを起動することなく本文をすぐに返します。

2. 通常の HTTP ＋抽出。 サーバーが HTML を返した場合、trafilatura が静的な応答から記事本文を抽出し、整形された Markdown にします。静的 HTML に「JavaScript が必要です」というスタブしか返さないページなど、JavaScript のシェルをヒューリスティックで検出し、その場合は第 3 段階に進みます。

3. ヘッドレスブラウザー。 第 1 段階と第 2 段階で使用可能な結果が得られない場合は、patchright（検出回避パッチを適用した Playwright のフォーク）が実際の Chromium を操作し、trafilatura がレンダリング済みのコンテンツを抽出します。ヘッドレスブラウザーのインスタンスは呼び出しの間も 1 つだけ起動したままにします。ブラウザーを使う段階での初回取得時に遅延起動し、セッション中は起動したままにするため、以降の取得では Chromium の起動コスト（約 2～5 秒）ではなく、ページ遷移にかかる時間だけで済みます。

積極的なボット検出によって、ヘッドレスの patchright でもブロックされるサイトでは、headless=False を指定してください。これにより、表示される Chromium ウィンドウを使用します。処理は遅く、画面上でも目立ちますが、残っている課題の大半を解決できます。GUI 表示のブラウザーは、それが必要な取得ごとに起動・終了します。GUI 表示での取得は、通常の処理ではなく、頻度の低い回避策であるため、常時起動にはしません。

ブラウザーでページに移動した後、サーバーは DOM を定期的に確認して trafilatura を実行し、2 回連続の確認で同じ抽出結果が得られた時点ですぐに返します。そのため、通常のページでは分析ツール、広告、その他の遅れて読み込まれるリソースの完了を待つのではなく、数百ミリ秒以内に結果を返します。また、遅い SPA やボット対策の解除を待つ時間を確保し、早すぎるタイムアウトを防ぎます。

一般的な記事では、生の HTML と比べてトークン数を約 80％、アクセシビリティツリーの完全なスナップショットと比べて約 90％削減できます。

インストール

Python 3.10 以降と、初回の Chromium のダウンロード（約 300 MB）が必要です。

# Run directly with uv (no install step)
uvx web-to-markdown-mcp

# Or install with pip
pip install web-to-markdown-mcp

# One-time browser download
patchright install chromium

MCP クライアントの設定

Claude Desktop

設定ファイルを編集します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "web-to-markdown": {
      "command": "uvx",
      "args": ["web-to-markdown-mcp"]
    }
  }
}

Claude Desktop を再起動します。

LM Studio

~/.lmstudio/mcp.json を編集します（Developer タブ → Edit mcp.json）。上記と同じ JSON ブロックを使用します。その後、Developer タブの Server Settings で Allow calling servers from mcp.json を有効にします。新しいチャットでは、Integrations タブにサーバーが表示されます。

Cursor / Windsurf / VS Code

各クライアントの MCP 設定場所に、同じ JSON ブロックを設定します。

Claude Code

claude mcp add web-to-markdown -- uvx web-to-markdown-mcp

使い方

このサーバーは、単一のツールを公開します。

fetch_url_as_markdown

パラメーター	型	デフォルト	説明
url	string	必須	取得する URL
wait_until	string	"domcontentloaded"	ナビゲーション完了のタイミング："load"、"domcontentloaded"、"networkidle"、"commit"
timeout_ms	int	60000	ナビゲーション手順のタイムアウト（ミリ秒）
headless	bool	true	false にするとブラウザーウィンドウが表示されます。動作は遅くなりますが、ボット検出をより回避できます
poll_budget_ms	int	5000	ナビゲーション後、コンテンツが安定するまで待機する最大時間
poll_interval_ms	int	250	ポーリング中に抽出を再試行する間隔

戻り値： Markdown 文字列。予期される失敗（タイムアウト、抽出可能なコンテンツがない、ナビゲーションエラー）の場合は、"ERROR:" で始まる文字列を返します。

呼び出し例（任意の MCP クライアントのツール使用 UI から）：

fetch_url_as_markdown(url="https://example.com/long-article")

wait_until の選択肢：

• "domcontentloaded"（デフォルト）— DOM の構築が完了した時点で返します。残りはコンテンツ安定化のポーリングで処理します
• "load" — すべてのサブリソース（画像、スクリプト、スタイルシート）の読み込みを待ちます。ポーリングはその後に実行されるため、必要になることはほとんどありません
• "networkidle" — ネットワークが静止するまで待ちます。バックグラウンド接続が継続するページでは、ハングすることがあります
• "commit" — レスポンスが開始した時点ですぐに返します。役立つ場面はほとんどありません

poll_budget_ms を増やすタイミング： デフォルトの 5 秒は一般的なページには十分ですが、数秒かけてコンテンツを描画する低速な SPA では抽出結果が不完全になることがあり、ヘッド付きモードではボット検出チャレンジが解除される前にタイムアウトする場合があります。ボット対策されたサイトをヘッド付きモードで取得する場合は、10000～30000 が妥当な設定です。

制限事項

• セッション中、最初にブラウザー層で取得する際の遅延。 ヘッドレスブラウザーは、必要な最初の取得時に遅延起動します（約2～5秒）。同じセッション中の2回目以降のブラウザー層での取得では、起動済みのインスタンスを再利用するため、ナビゲーション時間だけで済みます。
• 厳しいサイトでのボット検出。 patchright のヘッドレスモードは、多くのサイトで Cloudflare のデフォルト設定を回避できますが、積極的な Bot Fight Mode、Turnstile のインタラクティブなチャレンジ、商用のボット管理製品（PerimeterX、DataDome、Kasada）を使用するページや、Cloudflare 自身のマーケティングサイトでは、ヘッドレスの Chromium が依然として検出されます。headless=False を指定すると、表示されるブラウザーウィンドウを使い、これらのほとんどを回避できます。その代わり、取得のたびに数秒間 Chromium のウィンドウが画面に表示されます。
• ヘッドありモードのボットチャレンジには、十分なポーリング時間が必要です。 ボット保護されたサイトで headless=False を使う場合、チャレンジの解除には5～15秒かかることがあります。このような場合は poll_budget_ms を10000～15000に設定してください。デフォルトの5000では、チャレンジの解決中に処理が終了することがあります。
• ヘッドありモードにはディスプレイが必要です。 headless=False は、グラフィカル環境のないサーバー（クラウド VM、コンテナー、CI）では動作しません。そのような環境でヘッドありモードが必要な場合は、Xvfb などの仮想ディスプレイを使用してください。
• データセンターの IP アドレス。 Cloudflare の厳しいチャレンジでは、ブラウザーのフィンガープリントやヘッドあり／ヘッドレスモードにかかわらず、データセンターの IP アドレス（Oracle Cloud、AWS など）からのリクエストは引き続きブロックされます。最良の結果を得るには、一般家庭のネットワーク接続から実行してください。
• SPA のレンダリングが遅い場合。 数秒以上かけて段階的にコンテンツをレンダリングするページでは、poll_budget_ms を増やしてください。デフォルトでは、時間切れ時に直近の抽出結果を返すため、まだレンダリング中の SPA では結果が不完全なことがあります。
• 認証が必要なコンテンツ。 このサーバーでは、Cookie や保存済みの認証情報がない、クリーンなブラウザーコンテキストを使用します。ログインが必要なページは動作しません。

関連ツールとの比較

• @playwright/mcp（Microsoft）— ナビゲーション、クリック、フォーム入力、JS の実行、アクセシビリティスナップショットの取得など、汎用的なインタラクティブブラウザー自動化を提供します。ページを操作する必要がある場合に使用してください。ページを読む必要がある場合は、このサーバーを使用してください。
• mcp-server-fetch などの HTTP ベースのサーバー — こちらもまず通常の HTTP を試すため、静的サイトでは動作が似ています。違いが出るのは、JS でレンダリングされるページやボット保護されたサイトです。これらのツールにはブラウザーによるフォールバックがないため、このサーバーで成功する場面でも失敗します。
• vadimfedenko/visit-website-reworked や npacker/web-tools などの LM Studio Hub プラグイン — LM Studio のプラグインシステム内で同じ考え方を実現します。このサーバーは、あらゆる MCP クライアントで動作します。

ロードマップ

• コールドスタートを平均化するための、ヘッドレスブラウザーインスタンスの永続化
• Cloudflare の Markdown for Agents 向けの Accept: text/markdown 高速パス
• 抽出範囲を限定するオプションの selector パラメーター
• ビューポート、ユーザーエージェント、ロケールを上書きするオプション
• Cookie や WAF の信頼状態を保持する、永続的なブラウザーコンテキストのオプション
• 同梱の Chromium ではなく、インストール済みの Google Chrome を使用する channel="chrome" オプション（最も厳しいサイトに対するステルス性をさらに向上）

コントリビューション

Issue や PR を歓迎します。大幅な変更を行う場合は、まず Issue を作成して、方針を相談してください。

ライセンス

MIT — LICENSE を参照してください。