MrScraper MCP

Web スクレイピングと Google 検索のための MrScraper MCP サーバー

MrScraper MCP は、Model Context Protocol 向けの MrScraper 公式サーバーです。2 つの SDK 互換ツールに加え、 アカウント確認機能を通じて、AI アシスタントをページのコンテンツや Google 検索に接続します。 scraperAPI で HTML、Markdown、またはスクリーンショットを取得し、 webSearch でページを見つけ、status でプランとトークン使用量を確認できます。

OAuth サインインでホスト型サーバーを使用するか、 オープンソースサーバーを ローカルで実行できます。セットアップ手順とクライアント設定については、 MrScraper MCP ドキュメント を参照してください。

サーバーは 3 つのツールを公開します。

scraperAPI  webSearch  status

デプロイの選択肢

選択肢	エンドポイントまたはコマンド	最適な用途
ホスト型	https://mcp.mrscraper.com/mcp	マネージドの Streamable HTTP 接続
ローカル HTTP	TRANSPORT=http npx -y @mrscraper/mcp@latest	セルフマネージドの HTTP サービス
ローカル stdio	npx -y @mrscraper/mcp@latest	ローカルプロセスを起動する MCP クライアント

ホスト型サーバーでは OAuth 2.1 を使い、ブラウザー経由でサインインするため、 コピーするキーはありません。セルフホスト型と stdio のセットアップでは、 app.mrscraper.com/api-tokens の MrScraper API キーを使用します。このキーはホスト型サーバーでも引き続き使用できます。

ホスト型サーバーに接続する

認証情報を指定せずに、MCP クライアントを https://mcp.mrscraper.com/mcp に接続します。 サーバーが OAuth チャレンジを返すと、クライアントがブラウザーを開き、 app.mrscraper.com で接続を承認します。

claude mcp add --transport http --scope user \
  mrscraper https://mcp.mrscraper.com/mcp

ファイルで設定するクライアントでは、headers ブロック全体を省略してください。

{
  "mcpServers": {
    "mrscraper": {
      "type": "http",
      "url": "https://mcp.mrscraper.com/mcp"
    }
  }
}

/mcp パスを含め、この URL をそのまま使用してください。これはアクセストークンの 発行対象となるリソース識別子です。アドレスの表記が異なる URL を対象に発行された トークンは拒否されます。

承認する内容

スコープ	許可する機能
scrape:read	webSearch
scrape:write	scraperAPI
account:read	status

スコープなしで呼び出されたツールは 403 insufficient_scope で拒否され、 クライアントから不足している権限の付与を求められます。

scraperAPI は、scrape:write を必要とする POST / でバックエンドに スクレイピングジョブを送信します。このスコープが告知される前に承認された接続では、 再度承認してスコープを付与する必要があります。scrape:read だけでは 書き込みアクセス権は付与されません。

接続を解除するには、MrScraper アカウントの「接続済みアプリケーション」から操作してください。 接続を解除するとリフレッシュトークンは直ちに失効し、発行済みのアクセストークンも 1 時間以内に使用できなくなります。

代わりに API キーで接続する

API キーは引き続きベアラートークンとして使用できます。セルフホスト型のデプロイや OAuth 非対応のクライアントでは、この方式を使用します。

{
  "mcpServers": {
    "mrscraper": {
      "type": "http",
      "url": "https://mcp.mrscraper.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MRSCRAPER_API_KEY"
      }
    }
  }
}

クライアントの環境変数機能またはシークレットストレージ機能を使用し、 キーがプロジェクトファイルに含まれないようにしてください。API キーには アカウントの全権限が含まれるため、スコープによる制限は適用されません。

Codex

export MRSCRAPER_API_KEY="YOUR_MRSCRAPER_API_KEY"
codex mcp add mrscraper \
  --url https://mcp.mrscraper.com/mcp \
  --bearer-token-env-var MRSCRAPER_API_KEY

MRSCRAPER_API_KEY を含む環境から Codex を起動してください。Codex は MCP 設定に環境変数名を保存します。

Claude Code

claude mcp add \
  --transport http \
  --scope user \
  --header "Authorization: Bearer YOUR_MRSCRAPER_API_KEY" \
  mrscraper https://mcp.mrscraper.com/mcp

Claude Code はプロジェクトスコープとローカルスコープにも対応しています。 接続をどの範囲で利用できるようにするかに応じて、スコープを選択してください。

コピーして使えるエージェント設定プロンプト

Connect MrScraper MCP to this agent. Detect the current MCP client and configure a Streamable HTTP server named mrscraper at https://mcp.mrscraper.com/mcp with no credential. The server uses OAuth 2.1, so the client will open a browser to sign in. If the client cannot do OAuth, fall back to a MrScraper API key from https://app.mrscraper.com/api-tokens stored through the client's environment-variable or secret-storage mechanism and sent as Authorization: Bearer <key>. Reload the MCP client when required, then list the tools and confirm that scraperAPI, webSearch, and status are the only available tools.

ツールの選び方

ツール	次の場合に選択してください
scraperAPI	ページ URL があり、HTML、Markdown、スクリーンショット、またはそれらの組み合わせが必要な場合。
webSearch	Google のクエリまたは Google 検索 URL があり、検索結果が必要な場合。
status	アカウントのプラン、トークン使用量、または残りのトークン数を確認する必要がある場合。

検出ワークフローは webSearch → scraperAPI です。どちらの Web ツールも readOnlyHint: true、openWorldHint: true、destructiveHint: false を指定しています。 status は読み取り専用で、オープンワールドではありません。認証は MCP 接続から行われ、API トークン引数を取るツールはありません。

以前のツールセットからの移行

登録されているのは scraperAPI、webSearch、status のみです。以前のほかのツール名は削除されています。

以前の呼び出し	置き換え
fetch	scraperAPI。POST、SDK オプション、自動ブラウザーフォールバック（デフォルト）を使用します。
serp	webSearch。query_or_url を url に、client_timeout を timeout に変更します。JSON には raw=false を設定します。
status	アカウントの使用状況には status を使用します。domain、from、to、action、api_token_name の入力はなくなりました。
scrape、rerun、results、result	この MCP サーバーから削除されました。

super_mode は super になります。home_page は warmStart に対応するようになり、 token_cap=0 が受け入れられます。更新後にサーバーを再起動し、MCP クライアントを再接続して、 tools/list を再取得してください。

ツールリファレンス

scraperAPI と webSearch のオプションおよびデフォルト値は、Python SDK の scraper_api メソッドと web_search メソッドに準拠しています。MCP ツール名にはキャメルケースを使用し、 引数名には SDK のスネークケースを使用します。

scraperAPI

POST https://api.mrscraper.com/

既知の URL から開始します。

{
  "url": "https://www.scrapethissite.com/pages/simple/"
}

HTML、Markdown、スクリーンショットをまとめてリクエストします。

{
  "url": "https://example.com",
  "html": true,
  "markdown": true,
  "screenshot": true,
  "super": true,
  "home_page": true,
  "geo_code": "ID",
  "timeout": 120
}

browser_rendering を省略するか null を指定すると、サービスはブラウザーを使わずに試行し、その後ブラウザーでの読み込みにフォールバックします。true はブラウザーでの読み込みを強制し、false は無効にします。スクリーンショットを指定すると、browser_rendering=false の場合でも常にブラウザーでの読み込みが強制されます。super はこれとは独立して、実機経由のルーティングを選択します。

JSON 本文には url、maxRetries、および任意の tokenCap が含まれます。ページオプションはクエリパラメーターです。API キーの場合、リクエストには SDK 互換の token クエリパラメーターと Authorization／x-api-token ヘッダーも含まれます。OAuth JWT は Authorization を通じてのみ送信されます。

入力	デフォルト	API マッピング／目的
url	必須	本文の url。絶対 HTTP(S) ページ URL。
html	true	クエリの html。HTML をリクエストします。
markdown	false	クエリの markdown。Markdown をリクエストします。
timeout	120	クエリの timeout。1～300 秒の整数。トランスポートではさらに30秒が許可されます。
geo_code	"US"	クエリの geoCode。プロキシの国コード。
proxy_country	省略	クエリの proxyCountry。互換性のための国フィールド。
browser_rendering	省略	クエリの browserRendering。true／false、または自動フォールバックの場合は省略／null。
super	false	有効時、クエリに super=true を指定します。
use_proxy	true	無効時、クエリに useProxy=false を指定します。
proxy	省略	クエリの proxy。カスタムの username:password@host:port プロキシ。
wait_for_selector	省略	クエリの waitForSelector。待機する CSS セレクター。
home_page	false	有効時、クエリに warmStart=true を指定します。
screenshot	false	クエリの screenshot=true。browserRendering=true も設定します。
block_resources	false	クエリの blockResources=true。画像、CSS、フォントをブロックします。
bypass_proxy	false	クエリの bypassProxy=true。プロキシバイパス／リソースブロックオプション。
cookie_jar	省略	クエリの cookieJar。Cookie 設定文字列。
headers	省略	クエリの headers。対象リクエストのヘッダー。オブジェクトまたは JSON 文字列。
max_retries	3	本文の maxRetries。0以上の整数。0を指定するとリトライを無効にします。
token_cap	省略	本文の tokenCap。0以上の整数のリトライトークン上限。
stream	省略	クエリの stream。レスポンスは通常の MCP エンベロープにバッファーされます。
discard_token_secret	""	任意の x-discard-token-secret ヘッダー。

webSearch

POST https://sync.scraper.mrscraper.com/api/google/serp/v2/sync

Google の検索結果をパースしてリクエストします。

{
  "url": "MrScraper web scraping",
  "raw": false,
  "region": "id",
  "language": "id",
  "page": 1,
  "format": "json"
}

raw=true は Python SDK と互換性のあるデフォルト値で、format に関係なく HTML をリクエストします。パース済みの結果を取得するには、raw=false と format="json" を設定してください。

Google 検索 URL から、クエリ、ロケール、ページ番号を指定できます。

{
  "url": "https://www.google.com/search?q=web+scraping&gl=us&hl=en&start=20",
  "raw": false
}

これにより、query="web scraping"、region="us"、language="en"、page=3 が導出されます。明示的に指定したオプションは、URL から導出された値より優先されます。

入力	デフォルト	リクエストへのマッピング／用途
url	必須	検索テキストまたは Google URL。本文の query に正規化されます。
raw	true	本文の format="html" を強制します。false の場合は format を使用できます。
format	"json"	raw が false の場合の本文の format。json または html を指定します。
region	URL の値または省略	本文の region。gl より優先されます。
language	URL の値または省略	本文の language。hl より優先されます。
page	URL の値または省略	本文の page。1 から始まる正の整数で、start より優先されます。
render_js	false	本文の renderJs。動的な検索機能をレンダリングします。
timeout	600	ローカル HTTP のタイムアウト時間（秒）。本文には含まれません。

status

GET https://api.app.mrscraper.com/api/v1/subscription-accounts

status は入力を受け取りません。接続中のアカウントの本人情報（名前、メールアドレス、認証状態）、サブスクリプションの状態、トークン上限、トークン使用量、残りトークン数、使用率、レート制限、自動更新の設定、更新日を返します。これらのフィールドだけをコピーするため、未加工のアカウントレコードに含まれる API キーや Stripe 識別子がクライアントに渡ることはありません。

{
  "kind": "mrscraper-cli-status-summary",
  "source_endpoints": ["/subscription-accounts"],
  "status_code": 200,
  "data": {
    "account": {
      "subscription_status": "active",
      "enterprise": false,
      "token_usage": 61240,
      "token_limit": 100000,
      "token_remaining": 38760,
      "usage_percent": 61.24,
      "rate_limit": 0,
      "rate_ttl": 0,
      "auto_renew": true,
      "ends_at": "2026-12-01T00:00:00.000Z",
      "user": {
        "name": "Ada",
        "email": "[email protected]",
        "verified": true
      }
    }
  }
}

status を使用する OAuth 接続には、account:read スコープが必要です。

レスポンスのエンベロープ

scraperAPI と webSearch は、structuredContent および JSON テキストとして status_code、data、headers を返します。JSON の本文はパースされ、その他のレスポンス本文はテキストのまま返されます。status は上記の概要を返します。

scraperAPI のレスポンスでは、リクエストした表現が data に含まれます。screenshot は Base64 エンコードされた JPEG で、x-status-code は対象ページのステータスです。

{
  "status_code": 200,
  "data": {
    "html": "<!DOCTYPE html>...",
    "markdown": null,
    "screenshot": null,
    "token_usage": 3,
    "runtime": 18.02,
    "retry_count": 0,
    "error": null
  },
  "headers": {
    "content-type": "application/json",
    "x-status-code": "200",
    "token_usage": "3"
  }
}

パース済みの webSearch レスポンス（raw=false）では、オーガニック検索結果が data.data.organic に含まれます。

失敗時は error が含まれ、MCP の isError=true が設定されます。ネットワーク障害時の status_code は null です。認証情報を含むレスポンスヘッダーと JSON メタデータはフィルタリングされ、ネットワークエラーでは署名付きクエリの認証情報が秘匿されます。

手動テスト：一度に 1 つのツールを実行

scripts/test-tools.ts は、コンパイル済みのローカル MCP サーバーを stdio 経由で起動し、公開されているツールがちょうど 3 つであることを確認してから、ツールを 1 つ呼び出し、レスポンスを表示して終了します。別途サーバー用のターミナルを用意する必要はありません。ランナーは .env を読み込むか、シェルから MRSCRAPER_API_KEY または MRSCRAPER_API_TOKEN を読み込みます。各ツールの呼び出しでは、稼働中の MrScraper サービスを使用します。

リポジトリのディレクトリから、次のコマンドを個別に実行してください。

1. 依存関係をインストールします。

   npm ci
   

2. 現在のサーバーをビルドします。

   npm run build
   

3. API キーを設定します。

   export MRSCRAPER_API_KEY="YOUR_MRSCRAPER_API_KEY"
   

4. scraperAPI をテストします。

   npm run test:manual -- scraperAPI --url "https://www.scrapethissite.com/pages/simple/"
   

5. webSearch をテストします。

   npm run test:manual -- webSearch --query "MrScraper web scraping"
   

6. status をテストします。

   npm run test:manual -- status
   

webSearch のサンプルでは、raw=false、format="json"、米国の検索結果、英語を明示的に指定します。各コマンドは、成功すると Tools: scraperAPI, webSearch, status と PASS <tool> を表示します。終了コードは、成功時が 0、ツールまたは接続の失敗時が 1、コマンド引数が無効な場合が 2 です。

サポートされている任意のオプションをテストするには、完全な JSON オブジェクトを渡してください。

npm run test:manual -- scraperAPI --args '{"url":"https://example.com","markdown":true,"screenshot":true,"super":true}'

npm run test:manual -- webSearch --args '{"url":"web scraping","raw":false,"region":"id","language":"id","page":1,"render_js":true}'

すでに起動している HTTP MCP サーバーをテストするには、--target http://127.0.0.1:8000/mcp を追加してください。ローカル stdio のテストでソースを変更した場合は、再ビルドしてください。npm run test:manual -- --help でランナーのオプションを確認できます。

サーバーをローカルで実行

Node.js 20 以降が必要です。

git clone https://github.com/mrscraper-com/mrscraper-mcp.git
cd mrscraper-mcp
npm ci
npm run build

Streamable HTTP

TRANSPORT=http npm start

デフォルトのエンドポイントは http://127.0.0.1:8000/mcp です。

{
  "mcpServers": {
    "mrscraper": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MRSCRAPER_API_KEY"
      }
    }
  }
}

stdio

{
  "mcpServers": {
    "mrscraper": {
      "command": "npx",
      "args": ["-y", "@mrscraper/mcp@latest"],
      "env": {
        "MRSCRAPER_API_KEY": "YOUR_MRSCRAPER_API_KEY"
      }
    }
  }
}

Stdio では、認証情報としてまず MRSCRAPER_API_KEY が優先され、次に MRSCRAPER_API_TOKEN が使用されます。

認証とセキュリティ

トランスポート	認証情報
ホスト型またはローカル HTTP	OAuth 2.1 アクセストークン、または MrScraper API キー（Authorization: Bearer として指定）
ローカル stdio	MRSCRAPER_API_KEY、次に MRSCRAPER_API_TOKEN

HTTP トランスポートは OAuth 2.1 リソースサーバーです。RFC 9728 の保護されたリソースメタデータを /.well-known/oauth-protected-resource（および /mcp を末尾に付けたパス）で公開します。認証されていないリクエストには、クライアントがサインイン先を検出できるよう、そのドキュメントを示す WWW-Authenticate ヘッダーを付けて 401 を返します。

アクセストークンは、認可サーバーが公開する JWKS を使ってローカルで検証されます。トークンの aud クレームにはこのサーバーを指定する必要があるため、別の MrScraper サービス向けに発行されたトークンをここで再利用することはできません。

API キーは、ツールの実行前に MrScraper のアカウントエンドポイントで検証されます。いずれの場合も、各 HTTP リクエストではリクエスト元の認証情報が使用されます。サーバーの環境変数に設定された認証情報が HTTP トランスポートで使用されることはありません。

サーバーは、認証情報を含むレスポンスヘッダーをフィルタリングします。解析済み JSON の認証情報メタデータと、生成された curl コマンドに埋め込まれた認証情報は、いずれもマスキングされます。ページのコンテンツは data で引き続き利用できます。

ブラウザーからのオリジン付きリクエストは、信頼されたローカルオリジン、claude.ai と chatgpt.com、および MRSCRAPER_ALLOWED_ORIGINS で設定された完全一致のオリジンから受け付けます。サービス間で接続する MCP クライアントは通常、Origin ヘッダーなしで接続します。検出用ドキュメントは、どのクライアントも認証情報を持つ前に読み取れる必要があるため、オリジンのチェックより先に配信されます。

インタラクティブウィジェット

webSearch は、解析済み JSON 結果向けの自己完結型 Google 検索結果ウィジェットを返します。HTML レスポンスには、解析済みの結果をリクエストするよう促すメッセージが表示されます。status は、プラン、トークン使用量、使用量メーターを備えたアカウントウィジェットを返します。MCP Apps に対応していないホストでは、通常の JSON ツールレスポンスが表示されます。

厳格なホスト CSP によって外部リソースがブロックされるため、各ウィジェットはスクリプトとスタイルをインライン化した自己完結型ドキュメントです。各ウィジェットは、ツールがすでに返したデータを表示するだけなので、ネットワーク許可リストは空に設定されています。ソースは ui/ にあり、npm run build:widgets で src/widgets/bundles.generated.ts にバンドルされます。この処理は npm run build で実行されます。

Docker

docker build -f docker/Dockerfile -t mrscraper-mcp .
docker run --rm -p 8000:8000 mrscraper-mcp

イメージは 0.0.0.0 にバインドします。デプロイ環境に適したネットワーク制御を適用し、Bearer 認証を有効にしたままにしてください。

環境変数

変数	デフォルト	用途
TRANSPORT	stdio	stdio または http を選択します。
HOST	127.0.0.1	HTTP のバインドアドレスです。Docker イメージでは 0.0.0.0 を使用します。
PORT	8000	HTTP のリッスンポートです。
MRSCRAPER_API_KEY	-	主要な stdio 認証情報です。
MRSCRAPER_API_TOKEN	-	代替の stdio 認証情報です（Python SDK でも使用されます）。
MRSCRAPER_HTTP_AUTH	1	HTTP のベアラー認証を有効にします。
MRSCRAPER_OAUTH	1	API キーに加えて OAuth 2.1 アクセストークンを受け入れます。
MRSCRAPER_MCP_PUBLIC_URL	https://mcp.mrscraper.com	公開オリジンです。<origin>/mcp が必須のトークン対象者です。
MRSCRAPER_OAUTH_ISSUER	https://api.app.mrscraper.com	認可サーバーの発行者です。
MRSCRAPER_OAUTH_JWKS_URL	<issuer>/.well-known/jwks.json	アクセストークンの検証に使用する鍵セットです。
MRSCRAPER_ALLOWED_ORIGINS	-	HTTP サーバーへの呼び出しを許可する、カンマ区切りのブラウザーオリジンです。
MRSCRAPER_API_BASE_URL	MrScraper platform API	開発およびテスト用のプラットフォームエンドポイントの上書き設定です。
MRSCRAPER_FETCH_BASE_URL	MrScraper Web Unblocker	スクレーパー API エンドポイントの上書き設定です。
MRSCRAPER_SYNC_BASE_URL	MrScraper synchronous scraper API	ウェブ検索エンドポイントの上書き設定です。
MRSCRAPER_LOG_HTTP_PAYLOAD	off	信頼できる環境でのリクエスト本文の診断情報を有効にします。
MRSCRAPER_LOG_HTTP_PAYLOAD_MAX	8192	診断用ペイロードの最大長です。

トラブルシューティング

• 接続エラー： サーバー URL が /mcp で終わっていることを確認し、設定を変更した後に MCP クライアントを再読み込みしてください。
• 401 Unauthorized： OAuth の場合は、クライアントでサインインフローが再度実行されるよう、サーバーに再接続してください。API キーの場合は、HTTP 用のベアラーキー、または stdio 用の環境変数キーを確認してください。
• 403 insufficient_scope： トークンにツールが必要とするスコープがありません。再接続して追加の権限を承認してください。scraperAPI には scrape:write、webSearch には scrape:read がトークンに含まれている必要があります。
• サインインには成功するが、ツールが動作しない： サーバー URL が正確に https://mcp.mrscraper.com/mcp であることを確認してください。トークンの対象者はこの URL に紐付けられています。
• 403 Forbidden Origin： 正確なブラウザーオリジンを MRSCRAPER_ALLOWED_ORIGINS に追加してください。
• ツール入力エラー： 呼び出し内容を、ツールのパラメータ表および文書化されている SDK 互換のデフォルト値と照合してください。
• 上流のタイムアウト： 対象のリクエストにより長い時間が必要な場合は、scraperAPI.timeout（最大 300 秒）または webSearch.timeout を増やしてください。
• 新しいツールが表示されない： 新しいクライアントセッションを開始し、tools/list に scraperAPI と webSearch のみが正確に含まれていることを確認してください。

開発

npm ci
npm run format:check
npm run lint
npm test
npm run build
npm pack --dry-run

実行中の HTTP サーバーをスモークテストします。

npm run test:mcp -- \
  --target http://127.0.0.1:8000/mcp \
  --token "$MRSCRAPER_API_KEY"

npm run test:e2e は、手動ランナーを使用して、稼働中の MrScraper サービスに対して 2 つの新しいツールを順番に実行します。対象を変更するには -- --url URL --query QUERY を、HTTP を使用するには -- --target http://127.0.0.1:8000/mcp を指定してください。

MCP レジストリ

ホストされているサーバーの MCP レジストリマニフェストは server.json で定義されています。Streamable HTTP エンドポイントを記述し、このリポジトリとセットアップドキュメントへのリンクを含みます。

.github/workflows/publish-mcp-registry.yml は server.json を io.github.mrscraper-com/mrscraper-mcp として公開します。Actions タブから実行するか（Publish to MCP Registry → Run workflow）、server.json のバージョンと一致する v* タグをプッシュしてください。GitHub OIDC で認証し、このリポジトリに io.github.mrscraper-com/* 名前空間へのアクセス権を付与します。対話型の mcp-publisher login github が使えるのは組織のオーナーだけです。server.json と package.json のバージョンが異なる場合、ワークフローは失敗します。

詳しくは公式のレジストリ公開ガイドをご覧ください。レジストリのバージョンは変更できないため、メタデータを変更して公開する場合は、server.json で新しいバージョンを使用してください。このマニフェストを公開するとホストされているサーバーが登録されますが、新しい npm パッケージは公開されません。

ライセンス

MIT。詳しくは LICENSE をご覧ください。