Octocrawl

Octocrawl

リンクをひとつ。Web データをすぐに活用。
AI エージェントや RAG 向けに、Web ページから Markdown とデータを取得します。
生の HTML より少ないトークン数で、各結果に読み取り方法の記録が残ります。

Web サイト · ドキュメント · MCP を接続 · ブログ · 変更履歴

---

ページをスクレイピング。Web サイトをクロール。Web コンテンツを活用可能なデータに変換。

Octocrawl は、AI エージェント、RAG、リサーチ向けのオープンソースの Web スクレイピング・クロールツールキットです。ナレッジベース用のドキュメントを収集したり、比較用の商品詳細を抽出したり、分析用にWeb上の表や一覧をデータに変換したりできます。各ページにはソースの記録が付属します。

ブラウザーでページを試すか、ホスト型 MCP または REST API を通じてエージェントを接続してください。ホスト型サービスは、インストールも API キーも不要でお試しいただけます。

Octocrawlで何ができますか？

機能	できること
ページをスクレイピングする	LLMのコンテキストに使える読みやすいMarkdownに加えて、HTML、リンク、画像URL、ページのメタデータを取得します。ブラウザレーンではスクリーンショットもリクエストできます。
ウェブサイトをマッピングする	サイトマップやページ内のリンクからURLを見つけ、検索語で絞り込んで必要なページを探せます。
サイトまたはセクションをクロールする	開始URLからリンクをたどって各ページのコンテンツを収集します。パスのフィルター、深さ、ページ数を制限できます。
URLのリストをスクレイピングする	複数のURLをまとめて送信し、結果を到着次第取得できます。失敗したURLを含め、すべてのURLの結果を保持します。
構造化データを抽出する	表や繰り返し表示される一覧をJSONおよびCSVで取得できます。また、商品名、価格、ページラベルなどの対応フィールドにはJSON Schemaを指定できます。抽出ガイド。
動的なページを読み取る · ローカルアクション	コンテンツを抽出する前に、JavaScriptを実行し、コントロールをクリックし、スクロールし、追加項目を読み込み、ページネーションをたどります。ブラウザーアクション。
PDFレポートを読み取る	引用に使えるページマーカー付きで、PDFのテキストレイヤーを抽出します。CSV、JSON、プレーンテキストのURLからもテキストを取得できます。ファイルのサポート。
スケジュールに沿ってソースを再確認する · ローカルワーカー	モニターを実行し、再試行付きでそのイベントをHTTPSエンドポイントに送信します。モニターの設定。

ホスト版Octocrawlではスクレイピングとマッピングを利用でき、アカウントがあればクロールとバッチジョブも利用できます（1回のクロールで最大500ページ、1回のバッチで最大1,000 URL）。キーなしのリクエストはHTTPを使用し、アカウントキーを使うとブラウザレーンが有効になります。大規模なジョブ、ページアクション、モニターを利用するにはローカルで実行してください。セットアップとセルフホストの方法については、Octocrawlの実行を参照してください。ウェブプレビューでは、1日5ページ、名前付きフィールド最大20個までの単一ページを試せます。

Octocrawlを選ぶ理由

• エージェント内でウェブデータを利用できます。 MCPを通じてClaude Code、Cursor、OpenCode、Codexに接続するか、REST、TypeScript、Python、Vercel AI SDKを使って構築できます。
• 既定ではモデルを使わずに構造化フィールドを取得できます。 ページ自体から対応する値を読み取り、フィールドの根拠と明示的な欠損値を取得できます。モデルへのフォールバックはオプトインです。
• スクレイピングが不十分だった場合に把握できます。 チェック機能が、チャレンジページ、コンテンツの誤り、事実の欠落、切り捨て、コンテンツ不足を検出します。ブロックされた結果や失敗した結果には理由が付与されます。取得したエラーページにはステータスとMarkdownが保持されます。結果の状態。
• 結果をソースまでさかのぼって確認できます。 各ページには、URL、取得時刻、ステータス、抽出の根拠を記録したエビデンスレコードが付属します。観測されなかった値はnullのままです。
• 必要な場所で実行できます。 ホスト型サービスを利用するか、npxで実行するか、Docker Composeでセルフホストできます。サーバーはAGPL-3.0、クライアントライブラリはMITです。

Octocrawlが役に立ったら、リポジトリにスターを付けてください。

クイックスタート

ホスト版の Octocrawl にエージェントを接続します。開始時にキーは不要です（Claude Code、Cursor、OpenCode、Codex の手順）。

claude mcp add --transport http octocrawl https://mcp.octocrawl.dev/mcp

キーがない場合、HTTP 経由で 1 日に 20 ページを読み取ります。それ以上利用するには、サインインしてキーを作成してください。アカウントには毎月 1,000 クレジットとブラウザーレーンが付与されます。キーはヘッダーに設定し、URL には含めません。

claude mcp add --transport http octocrawl https://mcp.octocrawl.dev/mcp --header "Authorization: Bearer oc_…"

または、お使いのコンピューターで実行します。Node.js 22.13+ または 24+ が必要です。

npx octocrawl scrape https://example.com --markdown
pip install 'octocrawl-client[pandas]'   # the Python client of a running API (npx octocrawl serve); [pandas] for to_pandas()
npm install @octocrawl/sdk        # the TypeScript client; @octocrawl/mcp is the MCP server
npm install @octocrawl/ai-sdk     # scrape and map as Vercel AI SDK tools, on hosted Octocrawl by default

ページはまず HTTP 経由で読み取られます。ブラウザーでしか表示されないページの場合は、npx playwright install chromium を一度実行して Chromium をインストールしてください。それまでは、そのようなページを取得すると browser_not_installed 警告が返され、実行するコマンドも表示されます。

日次制限なしですべてのツールをエージェントに提供するには、API をローカルで実行し、MCP サーバーを接続します。

npx octocrawl serve                                  # keep it running: the API on 127.0.0.1:8787
claude mcp add octocrawl -- npx -y @octocrawl/mcp    # the published stdio server, a client of that API

ホスト型サービスでは、scrape と map を利用でき、アカウントを作成すると crawl と batch jobs も利用できます。ローカルサーバーでは、より大規模なジョブ、Amazon.sg の商品ツール、Monitor ツールが追加されます。他のマシン向けに自分でサービスを提供する場合、npx octocrawl serve --hosted --token <token> は、ホスト型サービスと同様に、プライベートアドレス、robots の上書き、保存済みログインを拒否します。Octocrawl の実行では 3 つの方法をすべて説明しています。Docker Composeを使うと、自分のサーバーで実行できます。エージェント（たとえば Cline）が Octocrawl をインストールする場合は、llms-install.mdに従ってインストールできます。

失敗時の表示

以下のテストページは HTTP 200 を返しますが、コンテンツではなく Cloudflare のチェックが表示されます（フィクスチャ block-challenge-200）。ステータスコードをそのまま信頼するクローラーは、これを成功として扱います。Octocrawl はプレーンな HTTP を試した後にブラウザーを使用し、ページがブロックされたことと、次に何をすべきかを報告します。

npx octocrawl scrape http://127.0.0.1:8799/block/challenge-200

{
  "status": "blocked",
  "blockReason": "cloudflare_challenge",
  "channelsTried": ["http", "browser_local"],
  "markdown": null,
  "snapshot": { "httpStatus": 200, "artifacts": [] },
  "usage": { "wallMs": 1079, "bytesWire": null, "externalCostUsd": 0 },
  "agentHints": [
    "127.0.0.1 gates automated access on the lanes tried (http, browser_local); … a proxy or session you own is the supported route, or, on your own machine, getting through the check yourself in your own Chrome: handoff: true on a scrape (octocrawl scrape --handoff) …"
  ],
  "evidenceRecord": { "schemaVersion": "w2l.evidence/1", "status": "blocked", "reason": "cloudflare_challenge", "lane": "browser_local", "…": "…" }
}

これは、リポジトリのフィクスチャサーバー（FIXTURE_PORT=8799 node --import tsx packages/fixtures/src/cli.ts）に対して実行した octocrawl 0.4.1 の実際の出力を省略（…）し、数値を丸めたものです。bytesWire: null はワイヤーバイト数を測定していないことを意味します。artifacts: [] はスクリーンショットも DOM スナップショットも作成されなかったことを意味します。

ドキュメント

サイトのドキュメントは octocrawl.dev/docs にあり、4 つのクライアント向けの MCP セットアップ、タスクガイド、制限事項を説明しています。これらは apps/public-web/content から生成されています。

完全なリファレンスは docs/ にあります。

トピック	ページ
octocrawl コマンド	コマンドライン
ホスト型、ローカル、セルフホスト型のサーバー、ポート、トークン、プロキシ、robots.txt	Octocrawl の実行
スクレイプのオプションと結果に含まれる情報	スクレイプのオプションと結果
複数の URL、サイト全体、サイトマップ、Webhook	バッチ、クロール、マップ
JSON Schema による構造化データ	JSON 抽出
PDF、CSV、XLSX、ZIP、JSON の URL	ファイル
ログイン、拡張アクセス、引き継ぎ、自分の Chrome	アクセス
定期的な再読み込みと HTTPS イベント	モニター
Firecrawl からの移行	Firecrawl 互換レイヤー

実際の実行例を紹介する記事はブログにあります：Claude Code と MCP による Web スクレイピング、RAG のための Web スクレイピング、Web サイトの全ページを検索する、自分の Chrome でログインが必要な Web サイトをスクレイピングする、LLM を使わずに構造化データを抽出する、URL のリストをスクレイピングして、すべての失敗を記録する。

研究者向けに、実際の実行例を順を追って説明する 2 つのガイドがあります：URL リストから証拠付き CSV を作成すると論文で Web データを引用する。

Monitor → result → HTTPS event → restart のワークフローについては、オンボーディングガイドをご覧ください。

コードに取り組む

Node.js 22.13+ または 24+ と npm が必要です。PDF エンジンの pdf.js には 22.13 以降が必要です。

git clone https://github.com/77777R7/Octocrawl.git
cd Octocrawl
npm ci
npx playwright install chromium
npm run typecheck
npm test
npm run scrape -- https://example.com --markdown
npm run crawl -- https://example.com --max-pages 20

パッケージはこのリポジトリから公開されます。毎週、Install check ワークフローが macOS、Windows、Linux で空のキャッシュから npx の行を実行します。

名前：Octocrawl と w2l

製品名は Octocrawl です。以前の開発時の名前は W2L（Web-to-LLM）でした。

一部の識別子には今も旧名が使われています。名前を変更すると既存のセットアップや記録に影響するため、意図的に変更するまではそのまま維持されます。

• W2L_API_PORT や W2L_TASK_ROOT などの環境変数。
• データディレクトリ .w2l/。
• 内部ワークスペースパッケージ @w2l/* と、チェックアウトに含まれる w2l コマンド（npm run w2l）。
• SDK クラス W2L と W2LError。
• Evidence Record のバージョン w2l.evidence/1。
• サイトの robots.txt で指定できる調査用 ID w2l-research。

公開パッケージでは、すでに新しい名前が使われています：octocrawl、@octocrawl/*、octocrawl-client。完全な一覧は AGENTS.md にあります。

ベンチマーク

フィクスチャスイートを、ベア HTTP ベースラインに対して実行します。

npm run bench

ベア HTTP ベースラインは、意図的に誤検知による成功率が高くなっています。コンテンツ抽出、チャレンジ検出、リダイレクト処理はありません。ベンチマークでは、期待される出力とスループットおよびクラッシュ後の復旧テストを紹介しています。

リポジトリの構成

packages/
  contracts/       TypeScript types and ground-truth schema (MIT)
  fixtures/        HTTP server with 56 ground-truth test cases
  http-core/       robots.txt parser (ReDoS-resistant)
  extract-tf/      Content extraction, HTML → Markdown, PDF text
  runtime/         TaskStore, frontier, bounded crawl orchestrator
  bench/           Benchmark runner, ladder CLI (w2l-ladder), scoring
  cli/             octocrawl: scrape, crawl, batch, map, serve (AGPL)
  api/             REST server (AGPL)
  sdk/             TypeScript client (MIT)
  ai-sdk/          scrape and map as Vercel AI SDK tools (MIT)
  mcp/             stdio and restricted Streamable HTTP MCP server (AGPL)
  public-preview/  Server for the public preview at octocrawl.dev

apps/public-web/   The octocrawl.dev site and its docs pages
python/            Python client octocrawl-client (MIT)
examples/          Runnable Monitor + Delivery workflow and webhook receiver
docs/              Reference, guides, ADRs and dated records (index: docs/README.md)
ROADMAP.md         The current phase and what is paused
CHANGELOG.md       Release notes

ロードマップ

ROADMAP.md では、最初に現在のフェーズの概要を説明しています。それ以前のマイルストーンチェックリストは docs/roadmap/milestones.md にあります。

コントリビューション

CLA の代わりに、Developer Certificate of Origin（DCO）を採用しています。すべてのコミットに Signed-off-by の行が必要です。

git commit -s -m "Your commit message"

ドキュメントの書き方などの詳細については、CONTRIBUTING.md を参照してください。

ライセンス

サーバー側のコード、CLI（@octocrawl/cli、octocrawl）、MCP サーバー（@octocrawl/mcp）：AGPL-3.0
クライアントライブラリ：MIT：TypeScript SDK（ワークスペースの @w2l/contracts も含み、こちらも MIT）、AI SDK ツール（SDK を含む）、Python クライアント（octocrawl-client）

このライセンスを選んだ理由については、PHASE1_ENGINEERING_NOTES.md §1.3 を参照してください。

AGPL を採用する理由

AGPL では、ネットワーク経由で提供する変更をオープンに保つことが求められます。変更を共有する限り、誰でも Octocrawl をフォーク、変更、ホストできます。本当の差別化要因は、ライセンスによる制限ではなく、名称（商標）とホスト型サービスです。