mcpField
Z
ZenRows MCP

ZenRows MCP

リモート
github.com/ZenRowsブラウザ自動化211 日前に更新
リポジトリ

ZenRows MCP について

ZenRows MCPは、実際のWebサイトやボット対策されたページの情報を必要とするAIエージェントやアプリ向けのWebデータサーバーです。スクレイピング、構造化抽出、クロール、バッチ処理、ブラウザー自動化をマネージド基盤で提供します。

主な機能

  1. 01ページをMarkdown、テキスト、HTML、PDF、画像で取得
  2. 02Webページから構造化JSONを抽出
  3. 03自動抽出に向けてドメインを準備
  4. 04非同期バッチ取得とサイトクロール
  5. 05ブラウザー、セッション、ページ操作の自動化

活用シーン

  1. 01ボット対策されたページから情報を収集
  2. 02商品ページや記事から項目を抽出
  3. 03サイトをクロールしてページ結果を取得
  4. 04フォームやクリックを伴うブラウザー作業を自動化

MCP 対応

スクレイピング、抽出、クロール、バッチ処理、ブラウザー自動化のツールをMCPクライアントに公開します。ホスト型Streamable HTTPエンドポイントとローカルstdioサーバーを提供します。

設定

リモートサーバーはインストール不要です。クライアントを選んで設定をコピーするか、ワンクリックで導入できます。

エンドポイントhttps://mcp.zenrows.com/mcp
インストールコマンドをコピー
Claude CodeTerminal
Cursor.cursor/mcp.json
VS Code.vscode/mcp.json
Claude Desktopclaude_desktop_config.json
Windsurf~/.codeium/windsurf/mcp_config.json

コマンドはターミナルで実行し、JSON は各クライアントの MCP 設定に貼り付けて再起動します。認可が必要なサーバーは初回接続時にログインを求めます。

すべてのエンドポイント
Streamable HTTPhttps://mcp.zenrows.com/mcp認証が必要
パッケージ
npm@zenrows/mcp2.17.0

ツール

43
パラメーター型必須説明
urlstringはいスクレイピングするウェブページの URL
js_renderbooleanいいえヘッドレスブラウザーによる JavaScript レンダリングを有効にします。SPA(React、Vue、Angular)やコンテンツを動的に読み込むページで必要です。
premium_proxybooleanいいえプレミアムな住宅用プロキシを使用してボット対策を回避します。強力に保護されたサイトで必要です。クレジット消費量が増加します。
proxy_countrystringいいえ地域を指定したスクレイピングに使用する国。ISO 3166-1 alpha-2 コード(例:'US'、'GB'、'DE')。premium_proxy=true が必要です。
response_typeenumいいえ出力形式。'markdown'(デフォルト)は構造を保持し、LLM に最適です。'plaintext' はすべての書式を削除し、純粋なテキストを抽出します。'pdf' はページの PDF を返します。'html' は未加工の HTML ソースを返します(response_type パラメーターを省略した場合の Zenrows のデフォルト)。autoparse、css_extractor、outputs、または screenshot パラメーターが設定されている場合は無視されます。markdown | plaintext | pdf | html
autoparsebooleanいいえページから構造化データを自動的に抽出し、JSON に変換します。製品ページ、記事、リスティングに最適です。
css_extractorstringいいえCSS セレクターを使用して特定の要素を抽出します。名前をセレクターに対応付ける JSON オブジェクトを指定します。例:'{"title":"h1","price":".price-tag"}'。ページ全体の内容ではなく JSON を返します。
wait_forstringいいえキャプチャ前に待機する CSS セレクターです。ページの初回レンダリング後に重要なコンテンツが読み込まれる場合に使用します。js_render=true が必要です。
waitintegerいいえページ読み込み後、コンテンツをキャプチャするまでの待機時間(ミリ秒)。最大 30000(30 秒)。js_render=true が必要です。
js_instructionsstringいいえスクレイピング前に実行するブラウザー操作の JSON 配列です。js_render=true が必要です。例:[{"click":"#load-more"},{"wait":1000},{"wait_for":".results"}]
outputsstringいいえ構造化 JSON として抽出するデータ型をカンマ区切りで指定します。使用可能な値:emails、headings、links、menus、images、videos、audios。「*」ですべての型を指定します。ページ全体のコンテンツではなく JSON を返します。
screenshotbooleanいいえページのファーストビューのスクリーンショットを撮影します。テキストコンテンツではなく画像を返します。視覚的な検証やデバッグに便利です。
screenshot_fullpagebooleanいいえファーストビューより下のコンテンツも含め、ページ全体のスクリーンショットを撮影します。テキストコンテンツではなく画像を返します。
screenshot_selectorstringいいえCSS セレクターを使用して特定の要素のスクリーンショットを撮影します。例:".product-card"。テキストコンテンツではなく画像を返します。

詳細

Zenrows MCP

Zenrows MCP サーバー

Zenrows MCP(Model Context Protocol)サーバーは、AI システムが Zenrows のウェブデータ基盤を利用するための標準的な方法です。1 つ接続するだけで、AI アシスタント、エージェント、またはアプリケーションが、保護されたウェブサイトも含め、ライブウェブに確実かつリアルタイムにアクセスできます。

npm version MIT License

📚 ドキュメント全文: docs.zenrows.com/mcp/overview


Zenrows MCP を選ぶ理由

  • 通常はボットをブロックするサイトにもアクセスできます。 自分でアンチボット対策を構築することなく、保護されたサイトへのアクセスを大規模かつ安定して実現できます。
  • 管理されたウェブデータ基盤です。 プロキシのローテーション、ヘッドレスブラウザーのオーケストレーション、アンチボット対策、セッション管理は、Zenrows のインフラストラクチャ上で実行されます。
  • すでに利用しているあらゆる AI に接続できます。 AI アシスタント、エージェントフレームワーク、AI SDK、IDE プラグイン、カスタムアプリケーションなど、あらゆる MCP クライアントで動作します。
  • スクレイピングコードは不要で、自然な言葉で指示できます。 タスクを自然な言葉で説明すると、AI が適切なツールを選びます。セレクター、プロキシ管理、アンチボット調整は不要です。

クイックスタート

Zenrows MCP は 2 つのトランスポート方式に対応しています。どちらも同じツールと機能を提供します。クライアントに合った方式を選んでください。

キーなしで利用できる機能:

  • ローカル(npx @zenrows/mcp): サインアップもキーも不要です。最初のツール呼び出しで、後から取得してキーと使用状況を引き継げる Free アカウント(月 5,000 クレジット)が作成されます。ZENROWS_AUTO_SIGNUP=false でオプトアウトできます。CI では、ZENROWS_API_KEY をシークレットとして設定するか、実行間で ZENROWS_HOME を永続化してください。
  • リモート(https://mcp.zenrows.com/mcp): initialize と tools/list はキーなしで応答します。ツール呼び出しにはキーが必要です(対応クライアントでは OAuth、それ以外では Bearer キーを使用します)。リモートサーバーが独自にアカウントを作成することはありません。ヘッドレスエージェントは POST https://app.zenrows.com/api/agent/signup で Free アカウントを作成し、返された apiKey を Bearer トークンとして使用できます。エンドポイントは最初に短い質問とともに 428 を返す場合があります。その場合は {"challenge_id": "...", "answer": "..."} を同じ URL に POST すると、キーを取得できます。
リモート MCP サーバー

AI アプリケーションが LLM API を直接呼び出す場合は、ホスト型の Zenrows MCP サーバーを使用してください。サーバーは Zenrows のインフラストラクチャ上で実行されるため、インストール、設定、更新は不要です。

サーバー URL:

https://mcp.zenrows.com/mcp

トランスポート: Streamable HTTP

認証: Bearer トークンとして OAuth または API キーを使用します。Zenrows API キーを各リクエストの Authorization ヘッダーに指定してください(または、対応クライアントで OAuth を完了してください)。

Authorization: Bearer YOUR_ZENROWS_API_KEY

ほとんどの MCP クライアントでは、ツール設定の authorization 省略記法フィールドで指定すると、自動的に Bearer トークンとして転送されます。クライアントによっては、代わりに自由形式の headers フィールドを使用します。どちらの方法でも動作します。

リモート MCP はアカウントを自動作成しません。initialize と tools/list はキーなしで動作しますが、キーなしでツールを呼び出すと、サインアップ用エンドポイント(agent_signup)を本文に示す 401 が返されます。クライアントで OAuth の「Create Free account」を使用するか、既存の API キーを指定してください。または、ヘッドレスエージェントから POST https://app.zenrows.com/api/agent/signup を実行します(匿名で実行でき、apiKey が返されます。最初に challenge_id と answer で回答する 428 の質問が返される場合があります。ネットワークごとの制限が適用されます)。その後、Authorization: Bearer <apiKey> を指定して再試行してください。

例:OpenAI Responses API
import os
from openai import OpenAI

ZENROWS_API_KEY = os.environ["ZENROWS_API_KEY"]
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.responses.create(
    model="gpt-5",
    tools=[
        {
            "type": "mcp",
            "server_label": "zenrows",
            "server_description": "Web scraping MCP server for accessing live web content.",
            "server_url": "https://mcp.zenrows.com/mcp",
            "authorization": ZENROWS_API_KEY,
            "require_approval": "never",
        }
    ],
    input="Visit https://news.ycombinator.com/ and summarize the three most recent posts.",
)

print(response.output_text)

フレームワーク固有の例を含む詳細な手順については、リモート MCP サーバーのドキュメントを参照してください。

ローカル MCP サーバー

MCP クライアントがリモート URL を呼び出すのではなく、サーバーをローカルのサブプロセスとして実行する場合は、ローカルの stdio 設定を使用します。これは、Claude Desktop、Claude Code、Cursor、Windsurf、VS Code、Zed、JetBrains IDE など、デスクトップ AI ツールや IDE プラグインで標準的なセットアップです。

パッケージ: npm の @zenrows/mcp

認証:

  1. ZENROWS_API_KEY 環境変数、または
  2. ~/.zenrows/secrets.json に以前保存したキー、または
  3. 自動サインアップ(デフォルト):どちらも設定されていない場合でも、サーバーは起動します。最初のツール呼び出し時に、POST /api/agent/signup 経由で Free プランのアカウントを作成し、キーとアカウント申請情報を ~/.zenrows/(secrets.json と account.json、モード 0600)に保存して、stderr に申請 URL を出力します。Zenrows から最初に簡単な質問が届くことがあります。その場合、ツール呼び出しは質問を返し、エージェントが account_signup_answer ツールで回答した後、再試行します。サインアップが拒否された場合(たとえば、CI でネットワークごとの上限に達した場合)、そのツール呼び出しは再試行可能な時期を示すエラーを返します。CI では、ZENROWS_API_KEY をシークレットとして設定するか、実行間で ZENROWS_HOME を保持してください。ZENROWS_AUTO_SIGNUP=false を設定すると、自動サインアップを無効にできます。この場合、キーが設定されるまでツール呼び出しはエラーを返します。サインアップリクエストには、マシンごとのランダム ID(Zenrows CLI と共有)と、ホストエージェントの推定値(claude-code、cursor など)も送信され、サインアップの出所を特定できます。どちらも省略するには、ZENROWS_TELEMETRY=off を設定してください。

要件: npx を使用できるよう、Node.js をインストールしてください。

設定(独自のキーを使用):

{
  "mcpServers": {
    "zenrows": {
      "command": "npx",
      "args": ["-y", "@zenrows/mcp"],
      "env": {
        "ZENROWS_API_KEY": "YOUR_ZENROWS_API_KEY"
      }
    }
  }
}

設定不要(自動サインアップ):

{
  "mcpServers": {
    "zenrows": {
      "command": "npx",
      "args": ["-y", "@zenrows/mcp"]
    }
  }
}

任意: ZENROWS_CRAWL_API_BASE は、crawl_* ツールの Crawl API ベース URL を設定します(デフォルトは https://api.zenrows.com/v1)。これらのツールを別のデプロイ先に接続する場合にのみ設定してください。

任意: ZENROWS_BATCH_API_BASE は、batch_* ツールの Batch API ベース URL を設定します(デフォルトは https://async.api.zenrows.com/v1)。これらのツールを別のデプロイ先に接続する場合にのみ設定してください。

この設定の正確な保存場所は、クライアントによって異なります。クライアントごとのファイルパスについては、クライアント別のセットアップガイドを参照してください。


ツール

Zenrows MCP では、次のツールファミリーを利用できます。

ツール目的
scrapeページ全体のコンテンツを Markdown、プレーンテキスト、HTML、PDF、またはスクリーンショットに変換します(補助出力も利用できます)。
extract構造化 JSON(extract=auto または css_extractor。autoparse は非推奨です)と、任意のステルスフラグを返します。extract=auto は現在無料(後日課金される可能性があります)で、準備済みのあらゆるドメインで、どの API キーでも動作します。parsed フィールドのみを返します。ページの HTML も取得するには、include_html: true を設定してください。エラー REQS007 の reason に理由が示されます。domain_not_prepared → prepare_domain を呼び出します(エラーには引数が含まれます。URL は 1 つでも動作します。同じページ種別の URL を 3 つ以上推奨するため、example_urls に最大 5 つまで追加してください)。page_not_recognised → ドメインは準備済みですが、このページは Extract が抽出する対象ではありません(ホームページのように抽出するものがないページなど)。代わりに商品、記事、または一覧ページを試してください。動作するはずのページなら数分後に一度再試行し、それでも動作しない場合は css_extractor を使用してください。再度準備する必要はありません。domain_not_enabled → 準備しても解決しないため、css_extractor を使用してください。エラーで autoparse が提示されることはなく、ツールが autoparse にフォールバックすることもありません。fallback_autoparse は非推奨で、効果はありません(true の場合、無視されたことを示す note が結果に含まれます)。
prepare_domain / prepared_domain_statusreason が domain_not_prepared の REQS007 が発生した後、extract(mode=auto)用にドメインを準備します。prepare_domain には、ドメインと 1~5 個のサンプル URL を指定します。1 つでも動作しますが、同じページ種別の URL を 3 つ以上指定することを推奨します(例:商品ページ 3 つ:https://www.example.com/products/a、/products/b、/products/c)。Extract は同じ種別のページを比較し、検出したフィールドを確認するとともに、あるページに不足しているフィールドを補完するためです。複数のページ種別を合わせて 5 つまで指定できます(例:商品ページ 3 つと検索結果ページ 2 つ)。status: "preparing" をすぐに返します(完了を待つことはありません)。クレジットは消費しません。準備には数分かかります。prepared_domain_status を約 30 秒ごとにポーリングし(ステータス、現在のステップ、失敗コード、アカウントの月間利用枠 used / limit / remaining、および今行うべきステップを示す next を確認)、status が ready になったら extract を再度呼び出してください。新しいドメインごとに利用枠を 1 つ使います。すでに準備済みのドメインは already_prepared: true を伴ってすぐに ready を返し、利用枠を消費しません。ドメインはホスト名で判定されます。shop.example.com と example.com は個別に準備され、先頭の www. は取り除かれます。
batch_create / batch_status / batch_wait / batch_results / batch_content / batch_list / batch_cancel / batch_pause / batch_resume / batch_rerun / batch_deleteCloud Batch API によるファンアウト(async.api.zenrows.com)。Fetch と同じクレジットを使用します。browser_batch ではありません。以下の Batch tools を参照してください。
crawl_create / crawl_get / crawl_results / crawl_content / crawl_download / crawl_list / crawl_stop / crawl_waitCrawl API(api.zenrows.com/v1/crawls)。新機能です。Crawl は現在も進化中です。新機能が追加され、上限が調整されることがあります。変更のたびに変更履歴で告知されます。開始 URL を 1 つ指定すると、同じ登録可能ドメイン上にあるリンク先の URL を取得します(サブドメインも対象です)。必要に応じて各ページの HTML も取得できます(output_format: "html")。crawl_create はすぐに返ります。crawl_wait を呼び出すと、件数と先頭 20 件の URL を確認できます。その後、crawl_download を呼び出してすべての結果をローカルの JSON Lines ファイルに保存するか(既定値は ~/.zenrows/crawls/<crawl_id>.jsonl。path は ~/.zenrows/crawls 内に収める必要があります。overwrite: true を指定しない限り、既存ファイルは保持されます。ホスト型サーバーはファイルを作成せず、代わりにダウンロード URL と curl コマンドを返します)、crawl_results でページを順に取得してください。深さに制限を設けない場合は、crawl_create で depth を省略します。max_pages または max_items(どちらも既定値は 100)に達するまでリンクをたどり、取得した各ページは scrape 1 回分として課金されます。再試行を安全に行うには、crawl_create で idempotency_key を設定してください。crawl_content には crawl_id と content_id(コンテンツ ID または結果の content_url)を指定します。読み取り処理は、429、502、503、504、およびネットワークエラーの場合に再試行します(最大 3 回。Retry-After を尊重し、最大 30 秒待機します)。crawl_create は idempotency_key が指定されている場合のみ再試行し、429 の場合は再試行しません。crawl_stop は 429、502、503、504 の場合に最大 3 回、合計最大 50 秒まで再試行します(停止処理の繰り返しは安全です。503 の crawl_busy は、停止がまだ保存されていないことを示します)。crawl_busy が解消されない場合は CRAWL_BUSY を返します。CRAWL_NOT_ENABLED が返される場合があります(このアカウントでは Crawl が有効になっていません)。
browser_*ブラウザーの完全な自動化に対応する 30 以上のツール(ナビゲーション、クリック、フォーム、JS、Cookie、タブ、セッション)。
バッチツール

バッチジョブは、多数の URL を非同期でスクレイピングします。通常の流れは、batch_create を実行し、ジョブが終了するまで batch_wait で待機し、batch_results で結果をページごとに取得してから、batch_content で特定のタスクのページを読み取ります。

  • batch_create は、最大 100,000 件のタスクをまとめた、追加できないジョブを送信します。各タスクには url(http または https、最大 2,048 文字)と、任意の external_id(英字、数字、.、_、- からなる最大 128 文字。重複可)、metadata(最大 20 個の文字列キーと値の組み合わせ、合計 4 KiB)、POST タスク用の method と body(本文は最大 16 KiB。対象が POST を複数回受信する可能性があるため、POST は読み取り専用クエリに使用します)、およびスクレイピングパラメーターを指定します。スクレイピングパラメーターは zenrows_params に指定するか、タスクに直接指定します。不明なタスクフィールドがある場合、何も送信される前に、該当するフィールド名を示して呼び出しが失敗します。response_type には markdown、plaintext、pdf を指定でき、省略すると HTML になります。タスクは、js_render または premium_proxy を明示的に指定しない限り、mode=auto を使用します。すべての呼び出しで Idempotency-Key が送信されます。idempotency_key を設定しない場合は自動生成されます。同じキーと本文を使って 24 時間以内に再試行すると、2 つ目のジョブではなく元のジョブが返されます。本文が異なる場合は BATCH_IDEMPOTENCY_CONFLICT になります。エラー応答には、再試行に使うキーが含まれます。wait: true を設定すると、実行が終了または一時停止したとき、あるいは wait_timeout(秒。デフォルトは 50)が経過したときに応答します。
  • batch_status と batch_wait は、最新の実行の status(pending、running、completed、stopped、failed)と stats を返します。batch_wait は実行が終了するまでポーリングし、一時停止中の実行では paused: true を即座に返し、一時的なエラーにも対応します。timeout は秒単位です(デフォルトは 50。多くのクライアントが呼び出しをキャンセルする 60 秒未満に設定されています)。タイムアウトすると、エラーではなく、現在の状態に ok: true、timed_out: true と注記を付けて返します。progressToken を指定した呼び出しでは、ポーリングのたびに進捗通知が送信されます。タスクの書き込みがまだ続いている実行(10,000 件以上の送信と、すべての再実行)では、ingesting: true になります。
  • batch_results は最大 limit 件(デフォルトは 100、最大 1,000)の結果行と next_cursor を返します。next_cursor を cursor として渡し、null になるまで繰り返します。status で all、successful、failed、processing を指定して絞り込めます。以前の実行を指定するには run_id を渡します。結果行の result_url は 2 時間有効な署名付き URL です。新しい URL が必要な場合は、一覧を再取得するか、batch_content を使用してください。結果はデフォルトで 14 日間保持されます。その後、成功した結果行は expired となり、result_url はありません。
  • batch_content は、1 つのタスクの結果を返します。テキスト(HTML、Markdown、プレーンテキスト、JSON)はインラインで返され、max_chars(デフォルトは 20,000)で切り詰められます。PDF は署名付きの result_url として返されます。大規模な実行では、結果の検索に複数回の呼び出しが必要になることがあり、その場合は応答に lookup_cursor が含まれます。まだ完了していないタスクは BATCH_TASK_NOT_READY、失敗したタスクは task_error を伴う BATCH_TASK_FAILED、期限切れのタスクは BATCH_RESULT_EXPIRED になります。
  • batch_list は、アカウントのジョブを新しいものから順に一覧表示します(1 ページあたりのデフォルトは 20 件、最大 100 件)。
  • batch_cancel は、現在の実行を完全に停止します。待機中のタスクは開始されず、実行中のタスクは完了して課金されます。結果は保持されます。batch_pause は実行を停止し、batch_resume で再開するまで一時停止します。一時停止中の実行もアクティブなジョブとしてカウントされます。これら 3 つのツールはすべて冪等で、すでに終了した実行に対して呼び出すと、最終状態と already_ended: true を返します。
  • batch_rerun は、最新の実行が終了した後に、新しい実行を開始します。デフォルトでは failed および pending のタスクを再実行し、その他のタスクは引き継ぎます。これは、クレジット切れまたはキャンセルによって実行が終了した場合の復旧方法です。ほかのタスクステータスを指定するには status を渡すか、すべてのタスクを再度スクレイピングするには full: true を指定します。一部のタスクのみを再実行できるのは、実行開始から 10 日後までです。Idempotency-Key が送信されます。
  • batch_delete は、ジョブとその実行および結果を削除し、アクティブなジョブ枠を空けます。 コスト:成功したタスクごとに、通常の API と同じクレジットを消費します。基本設定では 1 クレジット、js_render を使用する場合は 5 クレジット、premium_proxy を使用する場合は 10 クレジット、両方を使用する場合は 25 クレジットです。mode=auto では、正常に動作した設定で各タスクが課金されます。対象からの 404 および 410 の応答を除き、失敗したタスクは課金されません。アカウントでは、デフォルトで Crawl と共有する形で、同時に 3 件のジョブを実行できます。

実行が failed で終了すると、ok: false が返されます。error.code は該当する HTTP エラーと同じです(非アクティブなサブスクリプションの場合は BATCH_INSUFFICIENT_CREDITS、BATCH_KEY_CAP_REACHED、または AUTH_INVALID、それ以外の場合は BATCH_RUN_FAILED)。さらに、error.server_code(failure_reason)、error.job_id、およびアドバイスが含まれます。原因を解消してから、batch_rerun を実行してください。

エラーには、code、message、detail、server_code(Batch API 独自のコード)が含まれます。1 件のジョブに関する呼び出しの場合は、job_id も含まれます。

コード発生条件
BATCH_INVALID_REQUEST400:リクエストが拒否されました。invalid_tasks に最初の不正なタスクが記載されます。何も作成されていません。
AUTH_INVALID401:API キーが拒否された場合、または server_code が subscription_inactive の場合です。後者では、キーは有効ですが、Billing でサブスクリプションを修正する必要があります。
BATCH_INSUFFICIENT_CREDITS402:アカウントのクレジットが残っていません。
BATCH_KEY_CAP_REACHED402:この API キーがクレジット上限のいずれかに達しました。アカウントの他のキーは引き続き使用できます。
BATCH_ACCESS_DENIED403:このアカウントまたはキーでは Batch が有効になっていません。再試行しないでください。
BATCH_NOT_FOUND404:このアカウントに該当するジョブ、実行、またはタスクがありません(削除済みのジョブも含みます)。
BATCH_RUN_ENDED、BATCH_RUN_NOT_FINISHED、BATCH_NO_MATCHING_TASKS、BATCH_RERUN_WINDOW_EXPIRED、BATCH_NO_PRIOR_RUN、BATCH_IDEMPOTENCY_CONFLICT、BATCH_TASK_NOT_READY、BATCH_CONFLICT409:server_code によります。
BATCH_RESULT_EXPIRED410:ジョブの保持期間を過ぎています。
BATCH_TASK_FAILED422:タスクが失敗しました。task_error にエラーが含まれます。
BATCH_QUOTA_EXCEEDED429:クレジットを増やしても上限が変わらないジョブの制限に達しました(Crawl と共有するアクティブなジョブ 3 件、スケジュール済みジョブ 5 件)。
BATCH_RATE_LIMITED上記以外の 429。
BATCH_FAILED上記以外の HTTP エラー。
BACKEND_UNAVAILABLE応答がありません。再試行後もネットワークエラーまたはタイムアウトが発生しています。

読み取り操作では、429、500、502、503、504、およびネットワークエラーの場合に、最大 3 回まで再試行し、Retry-After に従います(最大 30 秒)。batch_create と batch_rerun では、500、502、503、504、ネットワークエラー、および Retry-After を伴う 429 の場合に、常に同じ Idempotency-Key を使って再試行します。ジョブ制限による 429 の場合は再試行しません。同じリクエストで BATCH_IDEMPOTENCY_CONFLICT が発生した場合は、キーを維持したまま batch_list を確認し、後でもう一度試してください。新しいキーを使うと、別の課金対象ジョブが作成される可能性があります。

スケジュール、Webhook、結果のエクスポート、CSV 入力、オープンジョブ(時間をかけてタスクを追加するジョブ)、実行、およびタスク履歴は、Batch API と Zenrows SDK からのみ利用できます。

AI は、プロンプトに基づいて適切なツールを選択します。コードからツールを直接呼び出す必要はありません。

各ツール、パラメーター、戻り値については、ツールの完全なリファレンスをご覧ください。


開発

git clone https://github.com/ZenRows/zenrows-mcp
cd zenrows-mcp
npm install
cp .env.example .env   # Optional: add your API key (stdio can auto-signup)
npm run dev            # Run with .env loaded (requires Node.js 20.6+)
npm run build          # Compile to dist/
npm run inspect        # Open the MCP inspector UI
Crawl のエンドツーエンドテストの実行

npm test はオフラインで実行されます。npm run test:e2e は、実際の MCP クライアントを介して稼働中の Crawl API に対し、crawl_* ツールを実行します。指定した開始 URL を対象に小規模なクロール(深さ 1、URL は最大 3 件、ページは最大 5 件)を作成して完了を待ち、結果と 1 件のページを読み込み、クロールを一覧表示し、終了したクロールを停止して、見つからない場合のエラーを確認します。最初の 3 つの変数が設定されていない場合はスキップされます。

  • ZENROWS_API_KEY:Crawl のアクセス権があるキー。
  • ZENROWS_CRAWL_API_BASE:Crawl API のベース URL。例:https://api.zenrows.com/v1。ローカル環境またはステージング環境のデプロイ先を指定すると、そちらに対してテストできます。
  • ZENROWS_E2E_CRAWL_URL:クロールする開始 URL。リンク先がアイテムページになっている一覧ページを指定します。
  • ZENROWS_E2E_CRAWL_INCLUDE(任意):include パターン。設定すると、すべての結果 URL にこの文字列が含まれていることをテストで確認します。
export ZENROWS_API_KEY=...            # a key with Crawl access
export ZENROWS_CRAWL_API_BASE=https://api.zenrows.com/v1
export ZENROWS_E2E_CRAWL_URL=https://example.com/products/
export ZENROWS_E2E_CRAWL_INCLUDE=/product/
npm run test:e2e

クロールの料金はキーのアカウントに請求され(ページ取得は最大 5 回)、Batch ジョブと共有されているアクティブなジョブ数の上限(デフォルトは 3 件)にもカウントされます。アカウントがこの上限に達している場合、テストは最大 5 分間、待機と再試行を行います。

リリース

Conventional Commit のタイトルを付けて PR をマージします。例:fix(extract): ... または feat(crawl): ...。fix、feat、perf にはスコープが必要です。

main へのマージ後、release-please が PR chore: release X.Y.Z を作成または更新します。package.json、 package-lock.json、server.json のバージョンを設定します。これらを手動で変更しないでください。

リリースするには、その PR をマージします。Release ワークフローがチェックを実行し、タグ vX.Y.Z と GitHub リリースを作成して、Publish ワークフローを開始します。この ワークフローは npm と MCP Registry に公開し、GHCR イメージをプッシュして、ホスト型サーバーをデプロイします。

既存のタグを再度公開するには、main からそのタグを指定して Release ワークフローを手動で実行します。

リリース PR のマージ後にチェックが失敗した場合

リリース PR では、他の PR と同様に CI が実行されます。マージ後、リリースの実行ではタグ付けと公開の前に、コードが再度チェックされます。そのチェックが失敗すると、main にはすでに新しいバージョンが反映されていますが、タグは作成されず、マージ済みのリリース PR には autorelease: pending ラベルが残ります。このラベルが次のリリース PR をブロックします。復旧するには:

  1. 通常の PR で問題を修正し、マージします。
  2. .release-please-manifest.json に記載されたバージョンを使い、修正コミットでリリースを作成します: gh release create vX.Y.Z --target <fix commit> --title vX.Y.Z --generate-notes --notes-start-tag <previous tag>
  3. マージ済みのリリース PR で、ラベル autorelease: pending を autorelease: tagged に置き換えます。
  4. main からタグ vX.Y.Z を指定して Release ワークフローを手動で実行します。

プルリクエストやイシューを歓迎します。


リソース


ライセンス

MIT

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。