cute-web-scraper

Claude にウェブスクレイピング機能を提供する MCP サーバー。 無料・ローカル・API キー不要・クラウドアカウント不要。

平易な英語で指示するだけ。ページを取得し、必要に応じて JavaScript をレンダリングし、ブロックを回避して、クリーンな Markdown またはクエリ可能なテーブルを返します。セレクタもグルーコードも不要です。

これが選ばれる理由

• アクセスできる。 4 段階のエスカレーション方式 — プレーンな HTTP、ブラウザの TLS フィンガープリント、実際のブラウザ、そしてステルスブラウザ。ASOS、eBay、Booking.com、Trustpilot はすべて、プロキシなしの自宅回線で実際のデータを返します。

• コンテキストを無駄にしない。 記事からナビゲーション、Cookie バナー、フッターを除去: BBC のニュースページは 20,513 文字から 3,198 文字 に。大量の結果は SQLite テーブルに格納され、チャットに貼り付ける代わりに SQL でクエリできます。

• 失敗を正直に伝える。 テストしたサイトのうち 5 つは 成功 ステータスで拒否を返しました — HTTP 200 の下でインタスティシャル、202 の下でボットチェック — そして 1 つは 403 で実際のコンテンツを返しました。ブロック検出はステータスコードではなくページ本文を重視するため、スタブをデータとして報告されることはありません。

• 単一ページではなくサイト全体。 サイトマップの検出、並列フェッチ、製品・連絡先・Shopify カタログ・場所・PDF・変更追跡をカバーする 24 のツール。

インストール

pipx install git+https://github.com/maccydee/cute-web-scraper

Chromium は js_render を初めて使用するときに自動的にダウンロードされます(一度きり、約 130MB)。

Related MCP server: mcp-server-scraper

Claude Code に接続

claude mcp add cute-web-scraper -- cute-web-scraper

あとは尋ねるだけ:

Scrape every product from https://example-shop.com and give me a CSV of name and price.

ツール

フェッチと発見

抽出

場所とローカルビジネス

変更追跡

結果テーブル

典型的な実行はこれらを組み合わせます: analyze_website → crawl_site → fetch_pages → query_table。

任意のフィールドの抽出

extract_by_selector は、固定抽出ツールがカバーしないすべてをカバーします:

Get the title, price and link from every product on these 40 pages,
save it as `catalogue`, then show me anything under £50.

fields は列名を CSS セレクタにマッピングします。row_selector は各マッチを 1 行にします — これがリストをテーブルに変換する仕組みです。@attr サフィックスはテキストではなく属性を読み取り、href と src は絶対 URL に解決されます:

{"name": "h3 a@title", "price": ".price_color", "link": "h3 a@href"}

ページの操作

fetch_page は actions を受け取ります。これらはページが読み取られる前に実行されます — Cookie ゲート、「さらに読み込む」ボタン、無限スクロール、検索フォームなど:

[{"action": "click", "selector": "#accept-cookies"},
 {"action": "scroll_to_bottom", "max_rounds": 10}]

利用可能なアクション: click、type、press、wait、wait_for、scroll、scroll_to_bottom、click_until_gone。各アクションは実行内容を報告するため、何もマッチしなかったステップも黙って無視されるのではなく、可視化されます。

ページではなく API を読む

サイトの解析が難しい場合、inspect_network はページをレンダリングし、行われたリクエストを報告します。JavaScript ページはほぼ常に、直接フェッチできるエンドポイントからデータを読み込みます — マークアップの解析より安価で、セレクタを壊すリニューアルにも耐えます:

Inspect the network on this listing page, then fetch whatever JSON endpoint it uses.

変更の監視

Check https://example.com/pricing for changes.

track_changes はスナップショットを保存し、new、same、changed を unified diff 付きで報告します。これはスケジューラなしの監視です — 好きなときにチェックして、差分だけを見ることができます。

スラッシュコマンド

サーバーには 4 つの既製ワークフローが同梱されており、Claude Code でスラッシュコマンドとして表示されます: scrape_site、scrape_shopify_store、find_contacts、compare_prices。

大規模スクレイピングの扱い

行を返すツールはすべて save_as を受け付けます。データを会話に入れる代わりに、結果テーブルを書き出して要約を返します:

Extract the whole catalogue from deathwishcoffee.com into a table called `catalogue`,
then tell me the price range and how many variants are out of stock.

Claude は extract_shopify_store(save_as="catalogue") を呼び出し、行数と列リストを受け取り、その後 query_table で回答します:

SELECT COUNT(*) AS variants, MIN(price) AS cheapest,
       MAX(price) AS dearest, SUM(available) AS in_stock
FROM catalogue

テーブルは 100,000 行を保持でき、そのどれも会話に入りません。query_table は厳密に読み取り専用です — 読み取り専用の SQLite ハンドルに対して実行され、SELECT 以外はすべて拒否するため、クエリが保存データを変更または削除することは決してありません。

テーブルは ~/.cute-web-scraper/results.db の SQLite ファイルに保存されます(SCRAPER_DB_PATH を設定すると移動できます)。

データのクリーニング

query_table も save_as を受け取り、結果を新しいテーブルとして永続化します。SQL は通常のクリーニング操作をすでに表現しているため、別の編集ツールセットはありません:

SELECT DISTINCT * FROM leads                                  -- deduplicate
SELECT street || ', ' || city AS address FROM leads           -- merge columns
SELECT name, phone FROM leads WHERE phone IS NOT NULL         -- drop columns and rows
SELECT vendor AS brand FROM catalogue                         -- rename

ソーステーブルは、意図的に自分の名前をターゲットにしない限り変更されず、その場合レスポンスは replaced_existing_table と表示されます — そのため、インプレースフィルタが行を黙って失うことはありません。

場所とローカルビジネス

find_places は単一の場所を検索し、find_places_nearby は半径内のカテゴリのすべてを返します。これはローカルリード生成のケースです:

Find every dentist within 4km of Bath, save it as `leads`,
then tell me how many have a website but no phone number.

カテゴリは親しみやすい名前(cafe、dentist、hotel、solicitor、gym、hairdresser など)または amenity=dentist のような生の OpenStreetMap タグを受け付けます。

データソースに関する注意。 これは OpenStreetMap であり、Google Maps ではありません。Google が明らかなターゲットでしたが、機能しません: 自動化されたブラウザは Cookie 同意インタスティシャルを受け取り、それを通過すると、場所パネルのない劣化したマップシェルが表示されます。ステルス層は役に立ちません。これはボット検出ではなく同意壁であり、ステルスが解決する問題とは異なる問題です。

OpenStreetMap は同じフィールド — 名前、住所、座標、電話、ウェブサイト、営業時間、カテゴリ — を、キー不要の文書化されたオープンエンドポイントを通じて提供します。唯一の同等物がないのは 星評価とレビュー数 で、これらは Google 独自のプロプライエタリデータです。

両方のエンドポイントはボランティア運営です。Nominatim の 1 秒あたり 1 リクエストのポリシーは、SCRAPER_DELAY_MS に関係なく内部で強制され、Overpass クエリは複数の公開ミラーにフォールバックします。メインインスタンスは負荷時に定期的に 504 を返すためです。

ツール出力も SCRAPER_MAX_INLINE_CHARS(デフォルト 25,000)で上限が設定されます。それを超えると、結果は save_as を指す注記付きで切り詰められます — そのため、1 回の呼び出しで誤ってコンテキストを埋めることはありません。

プロンプトの例

Export the whole catalogue from deathwishcoffee.com and tell me the price range.

Find all email addresses on https://company.com and its contact pages.

What platform is https://myblog.com on? Does it need JavaScript to scrape?

Scrape these 200 product pages into a table, then show me everything under £50 that's in stock.

Extract the social media links from these 10 agency sites: [urls...]

設定

すべては環境変数で、未設定でも動作するデフォルト値があります。

長いURLリストを1つのテーブルにバッチ処理するには、最初の呼び出し以降のすべての呼び出しで mode: "append" が必要です。そうしないと、各バッチが前のバッチを置き換えます。スパースに返ってくるレンダリング済みページには wait_ms を指定できますが、できればCSSセレクタ付きの wait_for の方が良いでしょう。

動作の仕組み

メインコンテンツのみ。ページ全体ではありません。 記事形式のページはtrafilaturaで処理され、本文を抽出して周囲の装飾を除去します。これは独立した2,008ページのベンチマークでReadabilityの0.674に対して0.791のF1スコアを記録したため採用されました。これは普遍的にではなくページごとに適用されます。同じベンチマークでは、製品グリッドやコレクション（「メインコンテンツ」が記事ではないページ）では抽出器のスコアが20〜30ポイント乖離するため、一覧ページは完全なドキュメントを保持します。任意の場所でそれを強制するには main_content: false を渡します。

4つの階層。拒否された場合のみ段階的に強化。 通常のHTTPクライアントがほとんどのページを処理します。サイトが拒否した場合、リクエストは実際のブラウザのTLSフィンガープリント（Chrome、次にSafari）で再試行されます。これは、一部のサイトがTLSハンドシェイク自体をフィンガープリントしており、ヘッダー変更では通過できないためです。js_render: true はシングルページアプリケーション用にChromiumでレンダリングします。最後の手段として、ステルスパッチを適用したブラウザが、JavaScriptを必要としかつ通常の自動化を拒否するサイトを処理します。

各階層は異なる失敗を修正し、どれも他の階層のスーパーセットではありません。TLS階層はJavaScriptを実行できず、Playwrightは検出可能な自動化ブラウザです。すべての結果はどの階層が処理したかを報告します。SCRAPER_IMPERSONATE=0 または SCRAPER_STEALTH=0 を設定すると、最後の2つを無効にしてブロックをそのままにできます。

最後の2つの階層は礼儀ではなく回避です。サイトが意図的に展開したボット検出を通過するために存在します。これらは拒否された後にのみ実行され、ページを正常に配信したサイトでは実行されません。

適応型バックオフ。 同一ドメインへのリクエストは SCRAPER_DELAY_MS で間隔が空けられ、開始から開始までで測定されるため、遅延は遅い応答に追加されるのではなくリクエストレートを制限します。ドメインが拒否した場合（429、403、Cloudflareチャレンジ）、そのドメインの遅延は最大60秒まで2倍になり、リクエストが再び成功すると減衰して戻ります。ドメインは独立して追跡されるため、2つのサイトを同時にスクレイピングしても追加コストはかかりません。

robots.txt は強制されません。 これはサイトマップを見つけるためだけに読み取られます。その Disallow ルールは参照されず、それを変更する設定もありません。適応型のドメインごとの遅延がこのツールの礼儀メカニズムです。

短いキャッシュ。 取得したページは5分間再利用されるため、同じURLに対して fetch_pages を実行してから extract_emails を実行しても、すべてを2回取得することはありません。

HTTPモード

デフォルトはstdioで、上記の claude mcp add が使用するものです。代わりに永続的な共有インスタンスを実行するには:

SCRAPER_AUTH_TOKEN=$(openssl rand -hex 16) cute-web-scraper --http --port 8080

claude mcp add --transport http cute-web-scraper http://127.0.0.1:8080/mcp

これは 127.0.0.1 にバインドし、/mcp と /health エンドポイントを公開します。ループバックを超えてバインドするには SCRAPER_AUTH_TOKEN が必要で、サーバーはそれを設定せずに起動を拒否します。ネットワークにオープンスクラッパーを静かに公開することはありません。

制限事項

• プロキシローテーションもCAPTCHA解決もありません。4つの階層すべてを生き延びたサイトは、推測ではなくブロックされたとして報告されます。

• LinkedInなどでは、SCRAPER_CHROME_USER_DATA_DIR をログイン済みのChromeプロファイルに指定する必要がある場合があります。

• SCRAPER_DELAY_MS=0 は礼儀の遅延を削除しますが、サイトが拒否した場合のバックオフは依然として機能します。

• 電話番号の抽出は意図的に保守的です。国コードまたは市外局番プレフィックスが必要なため、年号や注文番号を返す代わりに、一部の裸のローカル形式を見逃します。

開発

uv sync --extra dev

uv run pytest -v

uv run pytest -m integration -v -s

uv run ruff check src/ tests/ && uv run mypy src/cute_web_scraper/

ユニットテストは密閉されており、ネットワークに一切触れません。統合テストは実サイトにアクセスし、デフォルトの実行から除外されています。

ライセンス

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