crawlbrulee

🍮 crawlbrulee mcp

AI エージェントと開発者のための、EU ネイティブなウェブスクレイピングです。

crawlbrulee をエージェントに組み込みましょう。crawlbrulee 公式の mcp サーバーにより、Claude Code、Codex、Cursor、Claude Desktop などの mcp 対応エージェントが、ページのスクレイピング、サイトのマッピング、バックグラウンドジョブの実行、使用状況の確認を行うためのネイティブツールを使えるようになります。1 回の呼び出しで、あらゆる url をクリーンな markdown、スクリーンショット、メタデータ、リンクに変換します。

• すべてEU内で実行されます。 取得、レンダリング、キャッシュ、結果はすべてEUのサーバーから外に出ません。プロキシの出口は選択できる唯一のホップです。EUの出口を選べば、何も外に出ません。GDPRに準拠した設計で、データ処理契約も用意されています。
• モデル向けの出力です。 広告、ポップアップ、Cookieバナーを削除し、リンクを残したmarkdownを、プロンプトですぐ使える形で提供します。フルページのスクリーンショットは、画像モデルに適したサイズのタイルに分割して返せます。
• 面倒な処理はお任せください。 ページに必要な場合のヘッドレスChrome、国を選択できるローテーションプロキシ、自動リトライ、広告とCookieバナーの削除、キャッシュ、バックグラウンドジョブ、署名付きWebhookを備えています。
• 無料で始められます。 750クレジット。クレジットカードは不要です。

無料のapiキーを取得 → dashboard.crawlbrulee.com

サーバーの特徴：

• npxで実行でき、インストールは不要です。
• 内部では@crawlbrulee/sdkを使用しています。このmcpは薄いプロトコルアダプターにすぎません。
• ターミナルベースのエージェント向けのstdioトランスポート。
• 厳密で詳細なツールスキーマにより、エージェントはドキュメントを読まなくても、すべてのパラメーターの機能を確認できます。

このreadmeでは、mcpサーバー自体、そのツール、ホストへの接続方法を説明します。APIの動作（エンドポイント、パラメーター、エラーの仕様）については、 APIドキュメントをご覧ください。

---

インストール

1. キーを取得します。 crawlbruleeアカウントをお持ちでない場合は、 サインアップしてください。無料プランではクレジット カードは不要です。次に、ダッシュボードのメニューからトークンを開き、トークンを作成をクリックします。

2. 環境変数に設定します。 シェルのプロファイル（例：~/.zshrc）に追加し、 新しいターミナルを開いて、そこからエージェントを起動します。キーをエージェントの チャットに貼り付けないでください。チャット内の情報はすべて履歴に残ります。

export CRAWLBRULEE_API_KEY="cwbl_..."

3. 設定にキーを含めずにサーバーを追加します。 Claude Codeの場合：

claude mcp add crawlbrulee -- npx -y @crawlbrulee/mcp

その他のstdioホストも同じコマンドを実行します：npx -y @crawlbrulee/mcp。一部のホスト（Codex、 Cursor、Windsurf、Gemini CLI、Claude Desktop）では設定ファイルにキーまたは変数名を指定する必要があり、 VS CodeとClaude Codeプラグインではマスクされたプロンプトでキーを入力できます。 各ホストで使用するファイルと設定項目については、ドキュメントのmcp設定をご覧ください。

キーが動作しなくなった場合（invalid_credentials）、期限切れ、取り消し、または入力ミスの可能性があります。同じ手順で 新しいキーを作成して古いキーと置き換え、エージェントを再起動してください。

設定

環境変数	必須	説明
CRAWLBRULEE_API_KEY	はい	Authorization: Bearer …として送信されるapiキーです。取得方法はインストールをご覧ください。

mcpは起動時ではなく、最初にツールを呼び出したときに環境変数を読み込みます。そのため、 設定の入力ミスはサーバーの起動失敗ではなく、明確なツールエラーメッセージとして表示されます。APIでキーがどのように使用されるかは、 認証をご覧ください。

---

ツール

scrape

単一のurlを取得し、指定されたコンテンツ（markdown、クリーンな html、raw html、リンク、画像、スクリーンショット、ページメタデータ）を返します。 input — url だけが必須です。それ以外には適切なデフォルト値が設定されています。

{
  "url": "https://example.com",
  "extract": {
    "markdown": true,
    "links": true,
    "screenshot": { "type": "full_page", "device_mode": "desktop" },
  },
  "require_js": false,
  "proxy": "basic",
  "cleanup": { "ads_and_popups": true, "exclude_selectors": ["nav", "footer"] },
  "cache": { "max_age": 3600 },
  "location": { "locale": "en-US", "country": "US" },
  "zero_data_retention": false,
}

zero_data_retention（ブール値、デフォルトは false）を有効にすると、結果は共有キャッシュに保存されません。結果の配信に使用するデータは24時間保持された後、削除されます。この設定を有効にするには1クレジットが追加で必要で、組織で有効化する必要があります。scrape_async でも指定できます。詳しくはゼロデータ保持をご覧ください。

extract.elements を使った名前付きの値。 ページ全体の Markdown を読み取る代わりに、価格、タイトル、リンクなど、ページからいくつかの値を取得するには、それぞれに名前と CSS セレクターを指定します。値は同じ名前で elements 内に返されます。all: true を指定すると、一致するすべての値がリストとして返され、fields を指定すると、一致した各要素内の名前付きの値が読み取られます。追加クレジットはかかりません。scrape_async でも指定できます。

{
  "url": "https://books.toscrape.com/",
  "extract": {
    "elements": {
      "heading": "h1",
      "books": {
        "selector": "article.product_pod",
        "all": true,
        "fields": {
          "title": { "selector": "h3 a", "output": "attribute", "attribute": "title" },
          "price": ".price_color",
        },
      },
    },
  },
}
// → "elements": {
//     "heading": "All products",
//     "books": [{ "title": "A Light in the Attic", "price": "£51.77" }, ...]
//   }

一致する値がない場合、名前付きの値は null になります（all: true の場合は []）。制限とセレクターのルールについては、elementsをご覧ください。

output — スクレイピングの完全な結果です。ページのメタデータ（タイトル、OG タグなど）は metadata 内に返されます。抽出された images は絶対 URL として返されます。クエリ文字列は保持され、相対 src はページ URL を基準に解決されます。スクリーンショットは、エージェントが別途取得できる署名付きダウンロード URL として返されます。まれにスクリーンショットを撮影できない場合があります。他の出力も要求していた場合は、残りの結果は返されますが、screenshot フィールドは省略されます。一方、スクリーンショットのみを要求し、スクリーンショットを返せない場合は、代わりにエラーが返されます（コンテンツタイプがスクリーンショットに対応していない場合は unsupported_screenshot_output、HTTP 422）。この場合、課金されません。結果には page_status_code とトップレベルの response_meta.usage ブロックも含まれます。

{
  "url": "https://example.com",
  "requested_url": "https://example.com",
  "page_status_code": 200, // the site's own HTTP status for the final page
  "markdown": "...",
  "metadata": { "title": "Example Domain" },
  "response_meta": {
    "usage": {
      // total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost + zero_data_retention_credit_cost
      "total_credit_cost": 1,
      "engine_credit_cost": 1, // http 1, browser 3, screenshot 5, cache 0
      "proxy_multiplier": 1, // basic 1, advanced 5
      "screenshot_slicing_credit_cost": 0, // 1 when the screenshot was split into slices, otherwise 0
      "zero_data_retention_credit_cost": 0, // 1 when zero_data_retention added its credit, otherwise 0
      "engine": "http", // "http" | "browser" | "screenshot" | "cache"
      "proxy": "basic", // resolved tier actually used: "basic" | "advanced" (never "auto")
    },
  },
}

サイトが返したページはエラーではなく、結果として扱われます。 page_status_code は、リダイレクト後にサイトが最終ページに返した HTTP ステータスです。404、410、503 のページも、コンテンツとステータスが返されるため、コンテンツを信頼する前に page_status_code を確認してください。404 の場合、Markdown はサイトの「見つかりません」ページです。403、407、408、429、451 を除き、2xx と4xxのページは課金対象です。5xx のページは課金されません。サイトにまったく接続できない場合は、代わりにツールが target_unreachable エラーを返します（errorsをご覧ください）。

response_meta.usage に加えて、結果には致命的ではない warnings も含まれます。これはエージェントが判定に使用できる、安定した文字列コードです。ページが大きすぎる場合は拒否するのではなく切り詰められ、どの部分が切り詰められたかがコードで示されます。

code	ペイロードへの影響
screenshot_truncated	ページがスクロール撮影の高さ上限を超えていました。スクリーンショットにはページ上部が含まれます。
links_truncated	ページに30,000件を超えるリンクがありました。links 配列は上限で切り詰められているため、不完全です。
inline_images_truncated	ページに10,000件を超えるインライン画像がありました。images 配列は上限で切り詰められているため、不完全です。
raw_html_truncated	ページ本文が10,000,000文字を超えていました。raw_html はタグの途中ではなく、タグの境界で切り詰められます。
elements_truncated	elements の値が制限に達しました。elementsをご覧ください。

サイズに関係しないコードがもう1つあります。screenshot_unavailable は、スクリーンショットを要求したものの、HTTP エンジンからページがスクリーンショットなしで返されたことを示します。結果の残りの部分は引き続き返されます。

また、コンテンツタイプに適用されない抽出を要求した場合（例：JSON ファイルの metadata）、残りのペイロードはそのまま返されますが、フィールド名は unsupported_fields リストに含まれます。 すべての入力フィールド、そのデフォルト値、制約については、スクレイプエンドポイントに記載されています。各ブロックについては、抽出、スクリーンショット、プロキシとロケーション、キャッシュをご覧ください。

scrape_async

スクレイプジョブを非同期で送信し、接続を開いたままにせず、すぐにjob_idを取得します。時間のかかるスクレイプ（重い JavaScript のレンダリング、長いページの全ページスクリーンショット）に使用してください。1 回限りの簡単な取得には、同期型のscrapeツールをおすすめします。その後、ジョブがdoneになるまでscrape_statusをポーリングし、scrape_resultでページを取得します。

scrapeと同じ入力を受け取り、ジョブごとに任意で完了時のwebhookを指定できます。

{
  "url": "https://example.com",
  "extract": { "markdown": true },
  "webhook": {
    // Endpoint that receives one signed `scrape.complete` POST when the job
    // finishes. http/https (HTTPS required in production), max 2048 chars.
    "url": "https://hooks.example.com/cwbl",
    // Opaque correlation object echoed back verbatim in the delivery's
    // `data.metadata`. Serializes to at most 2048 bytes.
    "metadata": { "ref": "order-42" },
  },
}

出力 — { "job_id": "..." }。

webhookを指定すると、ジョブが終端状態に達したとき、署名付きのscrape.complete POST をお客様のエンドポイントに 1 回送信します。metadataはdata.metadataにそのまま含まれ、ジョブの使用状況はdata.response_meta.usageに含まれます。これにより、ポーリングせずに完了を確認し、コストを追跡できます。SDK のverifyWebhookSignatureを使ってX-Cwbl-Signatureヘッダーを検証してください（署名シークレットは、ダッシュボードの「アカウント」→「ウェブフック」で設定します）。

ジョブのライフサイクルについては非同期スクレイプに、配信仕様とペイロードの形式についてはウェブフックに記載されています。署名方式についてはウェブフックの検証をご覧ください。

scrape_status

非同期ジョブの現在のライフサイクルステータス（pending、running、done、failed）を確認します。失敗時にはerrorメッセージも返されます。ジョブがdoneになると、レスポンスにはresponse_meta.usageブロック（total_credit_costとその内訳、請求対象のengine、解決されたproxyティア）も含まれます。キャッシュヒットはengine: "cache"で示されます。サイトからページが返されたジョブは、そのページが 404 であってもdoneになります。結果のpage_status_codeを確認してください。doneになるまでポーリングし、その後scrape_resultを呼び出します。

{ "job_id": "..." }

scrape_result

完了した非同期ジョブの抽出済みコンテンツを取得します。同期型のscrapeツールと同じ形式の結果（page_status_code、metadata、elements、response_meta.usageを含む）を返します。ジョブがまだpendingまたはrunningの場合はエラーになるため、先にscrape_statusを確認してください。

{ "job_id": "..." }

map

Web サイトのリンクマップを作成（またはキャッシュ済みのものを取得）します。サイトマップの検出とホームページのリンク抽出を組み合わせます。選択したページをスクレイピングする前に、サイトのリンクを一覧表示するために使用します。各リンクは { url } だけです。

max_urls（デフォルトは 5000、最大 100000）は検出の予算であり、最後に件数を絞るものではありません。見つかった URL がこの数に達すると検出を停止するため、値を小さくするとクロールが速くなり、費用も抑えられます。limit（デフォルトは 5000、最大 10000）は回答をページ分割する場合にのみ使用します。

返される URL は、scrape が返す url と同じ方法で正規化されるため、map から scrape へ進んでも同じホストにとどまります。結果は、有用性の高いリンクから順に並びます。

レスポンスの response_meta には、pagination、truncation、および usage ブロック（total_credit_cost = engine_credit_cost × proxy_multiplier + zero_data_retention_credit_cost、請求対象の engine、解決された proxy ティア）が含まれます。map は多数のファイルを読み取るもので、単一のページを読み取るものではないため、スクリーンショットの分割機能も page_status_code もありません。サイトから請求対象外のステータス（たとえば 5xx）のみが返された場合や、何も返されなかった場合は、何も見つからなかった map の結果は空で、無料です。

{
  "url": "https://example.com",
  "sitemap_only": false,
  "types": { "internal": true, "external": false, "internal_subdomains": true },
  "max_urls": 5000,
  "page": 1,
  "limit": 1000,
  "zero_data_retention": false,
}

zero_data_retention は scrape と同様に機能します（zero data retention を参照してください）。

独自の max_urls に達して停止した map は、指定した数とちょうど同じ件数のリンクを返し、response_capped: false となります。サイトにさらにリンクがあることを示すのは truncation.discovery_cap_reason です。

{
  "truncation": {
    "storage_capped": false,
    "response_capped": false,
    "total_before_max_urls": 5000,
    "total_detected_before_storage_cap": 5000,
    "discovery_capped": true, // discovery stopped before reading every sitemap file
    "sitemaps_skipped": 3, // files skipped or only partly read
    "discovery_cap_reason": "max_urls", // retry with a higher max_urls
  },
}

discovery_cap_reason は max_urls、time、file_budget、depth、file_size、unread_files、または検出が中断されなかった場合は null のいずれかです。リクエストで増やせる上限は max_urls のみです。unread_files は、サイトが公開しているサイトマップファイルを今回読み取れなかったことを意味します。一時的な問題であることが多いため、後で再試行すると、より多くのリンクが返される場合があります。time、file_budget、depth、file_size は、サイト自体が大規模、低速、または階層が深いことを意味し、再試行しても改善しません。

検出ルールとページネーションの仕様については、map endpoint を参照してください。

usage

現在の請求サイクルのスナップショット（クレジットの合計／使用済み／利用可能数、使用済みクォータの割合、最大同時実行数、サイクルのリセット日時）を返します。引数は不要です。呼び出しにかかる費用とクレジットの計算方法については、credits & pricing に記載されています。

whoami

設定された API キーに対応する組織名、トークン名、および一部を伏せたトークンのプレビューを返します。クレジットを消費する操作の前に、使用中のアカウントを確認するのに便利です。

---

エラー

API 呼び出しが失敗すると、すべてのツールが MCP エラー結果（isError: true）を返します。エラーのテキストは一定の形式に従います。

[<errorName>] <message> (HTTP <status>)

一部のコードでは、その後に次の手順が簡潔に示されます（例：target_unreachable、zero_data_retention_not_enabled）。テキストの残りの部分ではなく、errorName コードに基づいて分岐してください。

エージェントは errorName コードに基づいて分岐できます。コードの一覧は、SDK の ApiErrorName ユニオンと、この MCP が追加する 2 つの合成コード（missing_api_key、internal_error）で構成されます。

コード	意味
missing_api_key	MCP ホストの環境変数に CRAWLBRULEE_API_KEY が設定されていません。メッセージにキーの取得方法が記載されています。
invalid_credentials	API がキーを拒否しました。期限切れ、取り消し済み、または入力ミスの可能性があります。メッセージに新しいキーの取得方法が記載されています。
service_unavailable	一時的なバックエンド障害（HTTP 503）です。キーに問題はありません。バックオフして再試行してください。
too_many_requests	レート制限に達しました。バックオフして再試行してください。
usage_allocation_error	プランのクレジット上限または同時実行数の上限を超えました。ユーザーに usage を表示してください。
validation_error	入力がサーバー側の検証に失敗しました。
invalid_url	フェッチ前に対象 URL が拒否されました。
blocked_url	対象 URL はブロックリストに登録されています。
antibot_blocked	接続先のアンチボット対策によってフェッチがブロックされました。
too_many_redirects	接続先がフェッチをリダイレクトのループにしました（HTTP 422）。対象側の問題です。むやみに再試行しないでください。
page_too_large	ページの HTML が大きすぎて処理できませんでした（HTTP 422）。終端エラーのため、再試行しないでください。
target_unreachable	サイトにまったく接続できませんでした（HTTP 502）。課金されません。後で再試行するか、URL を確認してください。
zero_data_retention_not_enabled	組織で zero_data_retention が有効になっていません（HTTP 403）。課金されません。
scrape_error	スクレイピングを完了できませんでした。サイトから提供されたページ（404 を含む）がこのエラーになることはありません。
unsupported_screenshot_output	スクリーンショットを取得できないコンテンツタイプに対する、スクリーンショットのみのリクエストです（HTTP 422）。課金されません。
not_found	非同期ジョブ ID が不明か、送信から 24 時間以上経過しています（scrape_status / scrape_result）。
request_timeout	ネットワークまたは読み取りのタイムアウトです。安全に再試行できます。
client_closed_request	完了前に呼び出し元がキャンセルしました。
internal_server_error	サーバー側で未処理の障害が発生しました。
crawlbrulee_error	型付きの名前を持たない SDK エラーです。
internal_error	この MCP のバグです。イシューを報告してください。

API ドキュメントには、正規のエラーリファレンスが記載されています。すべてのエラー名、その原因、復旧方法を確認できます。

---

開発

pnpm install
pnpm typecheck   # tsc --noEmit
pnpm lint        # eslint
pnpm test        # vitest run
pnpm build       # tsup → dist/index.js with shebang
pnpm verify      # all of the above

ビルド済みの MCP をローカルで実行します。

CRAWLBRULEE_API_KEY=cwbl_... node ./dist/index.js

MCP クライアントが標準入出力で接続するまで待機します。対話型デバッグには、MCP Inspector と組み合わせてください。

ドキュメント

この README では、MCP サーバー自体について説明します。インストール方法、ホストへの接続方法、公開するツールを扱います。API の動作（エンドポイント、パラメーター、エラーの仕様）については、API ドキュメントが正式な情報源です。MCP ガイドでは、ホストのセットアップについてさらに詳しく説明しています。

crawlbrulee ツールキットの一部

1 つの API を、さまざまな方法で呼び出せます。

• JS/TS SDK — @crawlbrulee/sdk（この MCP がラップする SDK）
• Python SDK — PyPI の crawlbrulee
• CLI — npx crawlbrulee
• MCP サーバー — @crawlbrulee/mcp（これです）
• エージェントスキル — スキル対応のコーディングエージェント向け

ドキュメント：crawlbrulee.com/docs · ダッシュボード：dashboard.crawlbrulee.com

ライセンス

Apache-2.0