Scrappey MCP Server

Scrappey MCP Server

Scrappey.com のブラウザーを利用したウェブ自動化およびデータ抽出機能を操作するための Model Context Protocol（MCP）サーバーです。smithery.ai/server/@pim97/mcp-server-scrappey で直接お試しいただけます。

概要

この MCP サーバーは、AI モデルと Scrappey のウェブ自動化プラットフォームをつなぐブリッジとして機能し、次のことができます。

• ブラウザーセッションを作成、管理する
• Scrappey のブラウザーを利用したインフラストラクチャ経由で HTTP リクエストを送信する
• ブラウザー操作（クリック、入力、スクロールなど）を実行する
• 一般的なボット管理システム（Cloudflare、Datadome、Kasada など）の JavaScript チャレンジページに依存するページをレンダリングする
• ページで必要な場合に、インタラクティブなチャレンジウィジェット（Turnstile、reCAPTCHA、hCaptcha など）を完了する
• スクリーンショットを撮影し、動画を録画する
• ネットワークリクエストをインターセプトする

このサーバーは、アプリケーションやインテグレーションのテスト、自分が運用するサービスの監視、アクセス権限のあるデータの収集など、正当な開発目的での使用を想定しています。責任ある使用をご覧ください。

セットアップ

インストール

npm install
npm run build

設定

1. Scrappey.com から Scrappey API キーを取得します
2. 環境変数を設定します。

SCRAPPEY_API_KEY=your_api_key_here

Claude Desktop の設定

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "scrappey": {
      "command": "node",
      "args": ["path/to/dist/scrappey-mcp.js"],
      "env": {
        "SCRAPPEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor IDE の設定

Cursor は設定から MCP サーバーをサポートしています。次のいずれかの方法で設定してください。

オプション 1：Cursor の設定 UI から

1. Cursor の設定を開きます（Ctrl+, または Cmd+,）
2. 「MCP」または「Model Context Protocol」を検索します
3. 次の内容で新しい MCP サーバーを追加します。
   • 名前：scrappey
   • コマンド：node
   • 引数：["C:\\Users\\pim_d\\Desktop\\scrappey.com\\mcp-smith\\mcp-server-scrappey\\dist\\scrappey-mcp.js"]
   • 環境変数：SCRAPPEY_API_KEY に API キーを設定します

オプション 2：設定 JSON から

1. Cursor の設定を開きます（Ctrl+Shift+P または Cmd+Shift+P）
2. 「Preferences: Open User Settings (JSON)」と入力します
3. MCP サーバーの設定を追加します。

{
  "mcp.servers": {
    "scrappey": {
      "command": "node",
      "args": ["C:\\Users\\pim_d\\Desktop\\scrappey.com\\mcp-smith\\mcp-server-scrappey\\dist\\scrappey-mcp.js"],
      "env": {
        "SCRAPPEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

注：MCP サーバーをインストールした場所に応じて、dist/scrappey-mcp.js のパスを調整してください。

設定後、Cursor を再起動して MCP サーバーを読み込みます。AI チャットインターフェースで Scrappey のツールを使用できるようになります。

利用可能なツール

1. セッションの作成（scrappey_create_session）

Cookie やその他の状態を保持する新しいブラウザーセッションを作成します。

{
  "proxy": "http://user:pass@ip:port",
  "proxyCountry": "UnitedStates",
  "premiumProxy": true,
  "mobileProxy": false,
  "browser": [{"name": "firefox", "minVersion": 120, "maxVersion": 130}],
  "userAgent": "custom-user-agent"
}

2. セッションの破棄（scrappey_destroy_session）

リソースを解放するため、ブラウザーセッションを適切に終了します。

{
  "session": "session_id_here"
}

3. セッションの一覧表示（scrappey_list_sessions）

現在のユーザーのアクティブなセッションをすべて一覧表示します。

{}

レスポンス：

{
  "sessions": [{"session": "abc123", "lastAccessed": 1234567890}],
  "open": 1,
  "limit": 100
}

4. セッションのアクティブ状態を確認（scrappey_session_active）

指定したセッションが現在アクティブかどうかを確認します。

{
  "session": "session_id_here"
}

5. リクエストの送信（scrappey_request）

JavaScript チャレンジページを自動的に処理しながら、ブラウザーを利用した HTTP リクエストを送信します。

{
  "cmd": "request.get",
  "url": "https://example.com",
  "session": "session_id_here",
  "postData": {"key": "value"},
  "customHeaders": {"User-Agent": "custom-agent"},
  "cookies": "session=abc123",
  "proxyCountry": "Germany",
  "premiumProxy": true,
  "cloudflareBypass": true,
  "datadomeBypass": true,
  "automaticallySolveCaptchas": true,
  "alwaysLoad": ["recaptcha", "hcaptcha"],
  "screenshot": true,
  "cssSelector": ".product-title",
  "innerText": true,
  "includeLinks": true,
  "includeImages": true,
  "interceptFetchRequest": "https://api.example.com/data",
  "abortOnDetection": ["analytics.com", "tracking.js"],
  "whitelistedDomains": ["example.com"],
  "blockCookieBanners": true
}

6. ブラウザー操作（scrappey_browser_action）

ブラウザー自動化の操作を実行します。

{
  "session": "session_id_here",
  "url": "https://example.com",
  "cmd": "request.get",
  "browserActions": [
    {"type": "wait_for_selector", "cssSelector": "#login-form"},
    {"type": "type", "cssSelector": "#username", "text": "myuser"},
    {"type": "type", "cssSelector": "#password", "text": "mypassword"},
    {"type": "solve_captcha", "captcha": "turnstile"},
    {"type": "click", "cssSelector": "#submit", "waitForSelector": ".dashboard"},
    {"type": "execute_js", "code": "document.querySelector('.user-data').innerText"}
  ],
  "mouseMovements": true
}

対応するブラウザー操作の種類：

操作	説明
click	要素をクリックします
type	入力フィールドにテキストを入力します
goto	URL に移動します
wait	指定したミリ秒数だけ待機します
wait_for_selector	要素が表示されるまで待機します
wait_for_function	JavaScript の条件が true になるまで待機します
wait_for_load_state	ページの読み込み状態（domcontentloaded、networkidle、load）になるまで待機します
wait_for_cookie	Cookie が設定されるまで待機します
execute_js	JavaScript コードを実行します
scroll	要素またはページの最下部までスクロールします
hover	要素にカーソルを合わせます
keyboard	キーボードのキー（enter、tab など）を押します
dropdown	ドロップダウンからオプションを選択します
switch_iframe	iframe に切り替えます
set_viewport	ブラウザーのビューポートサイズを変更します
if	条件付きで操作を実行します
while	条件が true の間、操作を繰り返します
solve_captcha	各種 CAPTCHA を解決します
remove_iframes	ページからすべての iframe を削除します

対応するインタラクティブチャレンジの種類：

• turnstile - Cloudflare Turnstile
• recaptcha / recaptchav2 / recaptchav3 - Google reCAPTCHA
• hcaptcha / hcaptcha_inside / hcaptcha_enterprise_inside - hCaptcha
• funcaptcha - FunCaptcha/Arkose Labs
• perimeterx - PerimeterX
• mtcaptcha - MTCaptcha
• custom - カスタム画像 CAPTCHA

7. スクリーンショット（scrappey_screenshot）

ウェブページのスクリーンショットを撮影します。

{
  "url": "https://example.com",
  "session": "optional_session_id",
  "screenshotWidth": 1920,
  "screenshotHeight": 1080,
  "fullPage": true,
  "browserActions": [
    {"type": "wait", "wait": 2000}
  ],
  "premiumProxy": true
}

チャレンジページへの対応

多くのサイトでは、コンテンツを返す前に JavaScript チャレンジページが表示されます。Scrappey はこれらを実際のブラウザーでレンダリングするため、自動リクエストで最終ページを取得できます。このサーバーは、一般的なボット管理システムのチャレンジページに対応しています。

• Cloudflare - Bot Management、Turnstile、チャレンジページ
• Datadome
• PerimeterX
• Kasada
• Akamai - Bot Manager
• Incapsula - Imperva

リクエストごとに特定のシステムへの対応を有効にします：

{
  "cloudflareBypass": true,
  "datadomeBypass": true,
  "kasadaBypass": true
}

上記のオプションキー（cloudflareBypass など）は Scrappey API のフィールド名であり、互換性のためそのまま使用します。

プロキシオプション

{
  "proxy": "http://user:pass@ip:port",
  "proxyCountry": "UnitedStates",
  "premiumProxy": true,
  "mobileProxy": true,
  "noProxy": false
}

対応国： UnitedStates、UnitedKingdom、Germany、France など。

エラーコード

このサーバーは詳細なエラー情報を提供します。

コード	説明
CODE-0001	サーバーの容量がいっぱいです。再試行してください
CODE-0002	Cloudflare にブロックされました
CODE-0007	Turnstile/プロキシエラー
CODE-0010	Datadome にプロキシをブロックされました
CODE-0024	プロキシがタイムアウトしました
CODE-0029	開いているセッションが多すぎます
CODE-0032	Turnstile CAPTCHA に失敗しました

一般的なワークフロー

1. セッションを作成します：

{"name": "scrappey_create_session"}

2. 移動して操作します：

{
  "name": "scrappey_browser_action",
  "session": "returned_session_id",
  "url": "https://example.com/login",
  "cmd": "request.get",
  "browserActions": [
    {"type": "type", "cssSelector": "#username", "text": "myuser"},
    {"type": "type", "cssSelector": "#password", "text": "mypass"},
    {"type": "click", "cssSelector": "#login-btn", "waitForSelector": ".dashboard"}
  ]
}

3. データを抽出します：

{
  "name": "scrappey_request",
  "cmd": "request.get",
  "url": "https://example.com/data",
  "session": "returned_session_id",
  "cssSelector": ".product-list"
}

4. 後片付けをします：

{
  "name": "scrappey_destroy_session",
  "session": "returned_session_id"
}

ベストプラクティス

1. 関連するリクエストでは、状態を維持するためにセッションを再利用します
2. リソースを解放するため、使用後はセッションを破棄します
3. より信頼性の高い接続には、プレミアムプロキシを使用します
4. チャレンジページを表示するサイトでは、自動チャレンジ対応を有効にします
5. ページの読み込み時間を確保するため、操作の間に適切な待機時間を設けます
6. 上限に達しないよう、セッション数の上限を監視します

責任ある使用

このサーバーは、ブラウザーベースの自動化とデータ抽出のための開発ツールです。次のような、合法かつ許可された目的にのみ使用してください。

• 自身が所有または運用するアプリケーションやインテグレーションのテストと監視
• アクセスを許可されているデータの収集

第三者のサイトにアクセスする際は、各サイトの利用規約、robots 指示、レート制限に従い、個人データと著作権を尊重するとともに、適用されるすべての法律を遵守してください。このサーバーおよび Scrappey アカウントの使用方法については、お客様が責任を負います。

デプロイ

Smithery へのデプロイ

# Build
npm run build

# Deploy via Smithery CLI
npx @anthropic/smithery-cli deploy

Docker

docker build -t scrappey-mcp .
docker run -e SCRAPPEY_API_KEY=your_key scrappey-mcp

リソース

• Smithery で試す
• Scrappey ドキュメント
• Scrappey API キーを取得

ライセンス

MIT License