Web Scrapper Service (MCP Stdin/Stdout & HTTP)

堅牢なヘッドレスWebスクレイピングのためのPythonベースのMCPサーバーです。Webページから主要なテキストコンテンツを抽出し、AIや自動化ツールとのシームレスな統合のためにMarkdown、テキスト、またはHTMLとして出力します。

主な機能

• ヘッドレスブラウザスクレイピング (Playwright, BeautifulSoup, Markdownify)

• Markdown、テキスト、またはHTMLでの出力

• MCP (Model Context Protocol) stdio/JSON-RPC統合向けに設計

• デュアルトランスポート: stdio (デフォルト) および共有サービスモード用のストリーミング可能なHTTP

• 永続的なブラウザプール: Chromiumがリクエスト間も起動し続けるため、高速なスクレイピングが可能

• スマートDOM待機: 固定の待機時間ではなく、MutationObserverベースのコンテンツ安定化機能

• Docker化済み、ビルド済みイメージを提供

• 環境変数による設定可能

• 堅牢なエラー処理 (タイムアウト、HTTPエラー、Cloudflareなど)

• ドメインごとのレート制限

• AIツールやIDE (Cursor, Claude Desktop, Continue, JetBrains, Zedなど) との容易な統合

• Cursor向けのワンクリックインストール、Claude向けの対話型インストーラー

Related MCP server: Fetcher MCP

クイックスタート

Dockerで実行 (stdioモード — クライアントごとに1コンテナ)

docker run -i --rm ghcr.io/justazul/web-scrapper-stdio

共有HTTPサービスとして実行 (1コンテナで複数クライアントに対応)

docker run -d --name web-scraper \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HTTP_PORT=8080 \
  -e BROWSER_POOL_SIZE=3 \
  -p 8080:8080 \
  --shm-size=3gb \
  ghcr.io/justazul/web-scrapper-stdio

またはDocker Composeを使用:

docker compose --profile service up -d

ワンクリックインストール (Cursor IDE)

トランスポートモード

stdio (デフォルト)

各MCPクライアントが docker run -i を介して独自のコンテナを起動します。シンプルで設定不要、あらゆるMCPクライアントで動作します。

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/justazul/web-scrapper-stdio"]
    }
  }
}

ストリーミング可能なHTTP (共有サービス)

HTTP経由で複数のMCPクライアントにサービスを提供する、永続的なコンテナを1つ実行します。複数のAIツールインスタンス (例: 複数のClaude Codeセッション) を実行する際にリソースを節約できます。

サービスを開始:

docker run -d --name web-scraper \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HTTP_PORT=8080 \
  -p 8080:8080 \
  --shm-size=3gb \
  ghcr.io/justazul/web-scrapper-stdio

MCPクライアントから接続:

{
  "mcpServers": {
    "web-scrapper": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

AIツールおよびIDEとの統合

このサービスは、Model Context Protocol (MCP) を実装する幅広いAIツールやIDEとの統合をサポートしています。以下に、主要な環境向けのすぐに使える設定例を示します。カスタムビルドが必要な場合は、必要に応じてイメージやタグを置き換えてください。

Cursor IDE

.cursor/mcp.json (プロジェクトレベル) または ~/.cursor/mcp.json (グローバル) に追加してください:

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

Claude Desktop

Claude DesktopのMCP設定 (通常は claude_desktop_config.json) に追加してください:

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

Claude Code

.mcp.json またはグローバルな ~/.claude.json に追加してください:

stdioモード (セッションごとに1コンテナ):

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/justazul/web-scrapper-stdio"]
    }
  }
}

HTTPモード (共有サービス — 最初にサービスを開始してください):

{
  "mcpServers": {
    "web-scrapper": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Continue (VSCode/JetBrainsプラグイン)

continue.config.json またはContinueプラグインのMCP設定に追加してください:

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

IntelliJ IDEA (JetBrains AI Assistant)

Settings > Tools > AI Assistant > Model Context Protocol (MCP) に移動し、新しいサーバーを追加してください。以下を使用します:

{
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "ghcr.io/justazul/web-scrapper-stdio"
  ]
}

Zed Editor

ZedのMCP設定に追加してください (正確なパスについてはZedのドキュメントを参照):

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

使用方法

MCPサーバー (ツール/プロンプト)

このWebスクラッパーはMCP (Model Context Protocol) ツールとして使用され、AIモデルやその他の自動化ツールから直接利用できます。

ツール: scrape_web

パラメータ:

• url (文字列、必須): スクレイピングするURL

• max_length (整数、オプション): 返されるコンテンツの最大長 (デフォルト: 無制限)

• timeout_seconds (整数、オプション): ページ読み込みのタイムアウト時間 (秒) (デフォルト: 30)

• user_agent (文字列、オプション): ブラウザに直接渡されるカスタムUser-Agent文字列 (デフォルトはランダムなエージェント)

• wait_for_network_idle (ブール値、オプション): スクレイピング前にネットワークアクティビティが落ち着くのを待つ (デフォルト: true)

• custom_elements_to_remove (文字列のリスト、オプション): 抽出前に削除する追加のHTML要素 (CSSセレクタ)

• grace_period_seconds (浮動小数点数、オプション): ナビゲーション後にJSレンダリングを待機する時間。スマート検出のためにMutationObserverを使用します。完全にスキップするには0に設定してください。(デフォルト: 0.5)

• output_format (文字列、オプション): markdown、text、または html (デフォルト: markdown)

• click_selector (文字列、オプション): 指定された場合、ナビゲーション後かつ抽出前に、このセレクタに一致する要素をクリックします

戻り値:

• Webページから抽出されたMarkdown形式のコンテンツ (文字列)

• エラーは [ERROR] ... で始まる文字列として報告されます

例: click_selector と custom_elements_to_remove の使用

{
  "url": "http://uitestingplayground.com/clientdelay",
  "click_selector": "#ajaxButton",
  "grace_period_seconds": 10,
  "custom_elements_to_remove": [".ads-banner", "#popup"],
  "output_format": "markdown"
}

プロンプト: scrape

パラメータ:

• url (文字列、必須): スクレイピングするURL

• output_format (文字列、オプション): markdown、text、または html (デフォルト: markdown)

戻り値:

• 選択した形式でWebページから抽出されたコンテンツ

注意:

• Markdownがデフォルトで返されますが、output_format を介してテキストやHTMLを要求できます。

• スクレイッパーはrobots.txtを確認せず、提供されたURLの取得を試みます。

• REST APIやCLIツールは含まれていません。これは純粋なMCP stdio/JSON-RPCツールです。

• スクレイッパーは常にWebページの完全な <body> コンテンツを抽出し、本質的なノイズ除去 (script、style、nav、footer、aside、headerなどの非コンテンツタグの削除) のみを適用します。スクレイッパーはCloudflareのチャレンジ画面を検出し、特定の文字列エラーを返します。

設定

環境変数を使用して、ほとんどの設定オプションを上書きできます:

コア設定

• DEFAULT_TIMEOUT_SECONDS: ページ読み込みとナビゲーションのタイムアウト (デフォルト: 30)

• DEFAULT_MIN_CONTENT_LENGTH: 抽出されたテキストの最小コンテンツ長 (デフォルト: 100)

• DEFAULT_MIN_CONTENT_LENGTH_SEARCH_APP: search.appドメインの最小コンテンツ長 (デフォルト: 30)

• DEFAULT_MIN_SECONDS_BETWEEN_REQUESTS: 同じドメインへのリクエスト間の最小遅延 (デフォルト: 2)

• DEFAULT_GRACE_PERIOD_SECONDS: JSレンダリングのデフォルト待機期間 (デフォルト: 0.5)

• DEBUG_LOGS_ENABLED: デバッグレベルのログを有効にするには true に設定 (デフォルト: false)

ブラウザプール

• BROWSER_POOL_ENABLED: 永続的なブラウザプールを有効にする (デフォルト: true)。リクエストごとのブラウザ起動 (元の動作) には false に設定してください。

• BROWSER_POOL_SIZE: 起動し続けるChromiumインスタンスの数 (デフォルト: 2)。各インスタンスは約100-200MBのRAMを使用します。

トランスポート

• MCP_TRANSPORT: トランスポートモード — stdio または streamable-http (デフォルト: stdio)

• MCP_HTTP_PORT: streamable-httpトランスポート使用時のHTTPサーバーポート (デフォルト: 8080)

• MCP_HTTP_HOST: HTTPサーバーのバインドアドレス (デフォルト: 0.0.0.0)

Cloudflareバイパス

• CAPTCHA_API_KEY: キャプチャ解決サービス用のAPIキー。設定すると、Cloudflare Turnstileチャレンジが自動的に解決されます。空の場合 (デフォルト)、CF保護されたページはエラーを返します。

• CAPTCHA_PROVIDER: キャプチャ解決プロバイダー — 2captcha、capsolver、または capmonster (デフォルト: 2captcha)

• CAPTCHA_BASE_URL: カスタム解決APIエンドポイント (デフォルト: プロバイダーの公式URLを使用)

• CAPTCHA_TIMEOUT: キャプチャ解決のタイムアウト時間 (秒) (デフォルト: 120)

テスト設定

• DEFAULT_TEST_REQUEST_TIMEOUT: テストリクエストのタイムアウト (デフォルト: 10)

• DEFAULT_TEST_NO_DELAY_THRESHOLD: テストで人工的な遅延をスキップするためのしきい値 (デフォルト: 0.5)

エラー処理と制限事項

• スクレイッパーは、ナビゲーションの失敗、タイムアウト、HTTPエラー (404を含む)、およびCloudflareのボット対策チャレンジを検出し、エラーを返します。

• レート制限はドメインごとに適用されます (デフォルト: リクエスト間2秒)。

• Cloudflareバイパス: 受動的な回避のために Patchright (CDPレベルの検知回避) を使用します。ほとんどのCF保護サイトは、チャレンジをトリガーすることなくスクレイピングされます。Turnstileチャレンジがトリガーされ、CAPTCHA_API_KEY が設定されている場合、サードパーティAPIを介して自動的に解決されます。

• 制限事項:

  • REST APIやCLIツールはありません (MCP stdio/JSON-RPCのみ)

  • HTML以外のコンテンツ (PDF、画像など) はサポートしていません

  • 保護されたページに対する認証やセッション管理はありません

  • 大規模なスクレイピングやサイトの利用規約に違反する目的での使用は意図していません

開発とテスト

テストの実行 (Docker Compose)

すべてのテストはDocker Composeを使用して実行する必要があります。Docker以外でテストを実行しないでください。

• すべてのテスト:

  docker compose up --build --abort-on-container-exit test

• MCPサーバーのテストのみ:

  docker compose up --build --abort-on-container-exit test_mcp

• スクレイッパーのテストのみ:

  docker compose up --build --abort-on-container-exit test_scrapper

ベンチマークの実行

docker compose run --rm benchmark

結果は benchmarks/RESULTS.md に保存されます。

貢献

貢献を歓迎します！バグ修正、機能追加、改善については、Issueを開くかプルリクエストを送信してください。大幅な変更を計画している場合は、提案を議論するためにまずIssueを開いてください。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。