PyreCrawl

🔥 PyreCrawl — AI エージェントにウェブ閲覧の超能力を

コマンドひとつで、あらゆる AI エージェントがウェブ全体を利用できます。 スクレイピング、抽出、クロール、マッピング、検索を、 セルフホスト可能で、API キーもレート制限もサブスクリプションも不要です。

PyreCrawl は、Claude、 Cursor、VS Code、Codex、OpenCode、Hermes、および MCP 対応のあらゆるエージェント向けの標準ツールインターフェースである MCP（Model Context Protocol）に対応しています。

スマートな自動フォールバック手順により、成功する最も低コストな方法が常に選ばれます。

fast HTTP
    │  (403/503/Cloudflare challenge or empty body)
    ▼
stealth browser (real Chromium + Cloudflare solver)
    │  (still blocked, or the page needs full JS rendering)
    ▼
deep processing (LLM-ready markdown, citations, structured extraction)

⚡ 提供されるツール

ツール	機能
scrape(url, prefer="auto")	単一 URL → LLM 向け Markdown
extract(url, schema)	スクレイピング + 構造化抽出（JsonCss スキーマ）
map_site(root, include_pattern=None, limit=200)	内部 URL をすべて列挙
crawl(root, max_pages=5, prefer="auto", include_paths=None, exclude_paths=None, max_depth=0)	パスフィルター + 真の BFS 深度に対応した複数ページのクロール
document(url)	PDF/DOCX/PPTX → Markdown（ブラウザー不要、オプションの [docs] extras）
search(query, limit=10)	DuckDuckGo HTML によるウェブ検索（API キー不要）
search_papers(query, limit=8, source="arxiv", category=None)	arXiv + Crossref による学術検索（API キー不要）— pdf_url を document に渡します
batch_scrape(urls[], ...)	1 回の呼び出しで多数の URL を処理 — 並列実行、重複排除、キャッシュ対応
deep_research(query, limit=5, scrape_top=3)	検索 → [n] 形式の引用付きエビデンスパック（LLM による統合は行わず、エージェントが実行します）
monitor(url, action, css_selector=None)	保存されたスナップショット + 統合差分による変更検知
session(session, action, ...)	永続的なブラウザーセッション（Cookie を保持）— ログイン制限ページ、複数手順の操作、スクリーンショット
cache(action)	HTTP レスポンスキャッシュの確認／消去／有効化／無効化
health()	バージョン + インポートの健全性チェック

MCP リソース（ツール呼び出しなしで読み取り専用の状態を取得）： pyrecrawl://cache/stats · pyrecrawl://sessions · pyrecrawl://monitors

MCP プロンプト（すぐに使える手順集）：research(topic) · rag_ingest(site) · watch_page(url)

環境変数フラグ

変数	デフォルト	効果
PYRECRAWL_CACHE	off	1 = インメモリ LRU（128 ページ）、またはディレクトリパス（ディスクモード用に予約）
PYRECRAWL_CACHE_TTL	900	キャッシュエントリーの有効期間（秒）
PYRECRAWL_MONITOR_DIR	~/.pyrecrawl/monitors	モニターのスナップショットを保存する場所
PYRECRAWL_NO_TELEMETRY	off	1 = 匿名の起動時 ping を無効化（DO_NOT_TRACK=1 にも対応）

prefer のオプション："auto"（デフォルトの手順） · "fast"（HTTP のみ） · "stealth"（CF バイパス） · "llm"（詳細処理）。

---

🚀 インストールと使い方（ワンライナー）

1. インストール

UV（推奨 — コマンドひとつで、Python のセットアップ不要）

UV は Python 自体も管理する高速な Python パッケージマネージャーです — Python を別途インストールする必要はありません。まず一度インストールします：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

UV の詳細はこちら →

その後、PyreCrawl を直接実行できます — venv も pip install も Python のダウンロードも不要です：

uvx pyrecrawl@latest

または uv tool install でインストール（永続的に使用、定期的な利用におすすめ）

uv tool install pyrecrawl

または pipx 経由でインストール（代替方法）

pipx install pyrecrawl

または venv に pip でインストール

pip install pyrecrawl

2. ブラウザーエンジンを一度だけインストール

pyrecrawl setup

これにより、Chromium とステルスブラウザーエンジンがインストールされます（約2分、初回のみ）。

3. AI エージェントに登録

# Auto-detect installed agents and write their MCP configs
pyrecrawl install

# Or target specific agents
pyrecrawl install claude-desktop cursor

# Dry-run to preview what would change
pyrecrawl install --dry-run

対応エージェント：claude-desktop、claude-code、cursor、vscode、codex、opencode、hermes。

4. チャットを開始

インストールと登録が完了したら、エージェントを再起動するか、新しいセッションを開始してください。次のように尋ねてみましょう。

「https://example.com をスクレイピングして、要約してください。」

利用可能なツール：

ツール	機能
scrape	単一の URL を取得して Markdown に変換（Cloudflare を検出すると自動的に回避処理を実行）
extract	スクレイピングし、CSS スキーマを使って構造化データを抽出 → JSON
map_site	ルートから内部 URL をすべて列挙
crawl	複数ページのクロール：一括で検出＋スクレイピング
batch_scrape	1回の並列呼び出しで複数の URL を取得
search	ボット対策を回避した DuckDuckGo によるウェブ検索
search_papers	学術論文の検索（arXiv / Crossref）
deep_research	検索＋スクレイピング＋引用を1回の呼び出しで実行 — 主要な調査ツール
document	PDF/DOCX/PPTX の URL からテキストを抽出
monitor	URL のコンテンツの経時的な変化を追跡
session	ログインが必要なページに対応する永続的なブラウザーセッション
cache	レスポンスキャッシュの確認または消去
health	エンジンの利用可能状況とバージョンを確認

さらに、ガイド付きプロンプトが3つあります：research、rag_ingest、watch_page。

使用例

特別な構文は不要です。エージェントに自然な言葉で尋ねてください。

伝える内容	エージェントが使う機能
「https://example.com をスクレイピングして、要約してください」	scrape → Markdown を返す → エージェントが要約
「Rust のメモリー安全性に関する脆弱性を調査してください」	deep_research → 検索＋スクレイピング＋引用
「世界各地の AI 規制について詳しく調査してください」	deep_research(iterations=3) → 検索クエリを改良しながら複数回にわたって調査
「このページから商品名と価格をすべて抽出してください」	extract → CSS スキーマ → 構造化 JSON
「https://docs.example.com をクロールして、概要を教えてください」	crawl → 複数ページ → 要約
「このページの価格の変化を監視してください」	monitor → ベースラインのスナップショット → 定期的な差分
「Transformer のアテンションに関する論文を見つけてください」	search_papers → arXiv の検索結果
「現在のキャッシュヒット率はどのくらいですか？」	cache → 統計情報

---

🧠 スキル — エージェントの調査品質を最大化

PyreCrawl のツールは、エージェントに手（スクレイピング、クロール、検索）を与えます。しかし、エージェントには依然として頭脳が必要です。つまり、どのツールをいつ使うか、調査をどのように連携させるか、そしてどのようなハルシネーション対策のルールに従うかを指示するものです。

それを提供するのが PyreCrawl Skills です。

	MCP ツール（このリポジトリ）	スキル（pyrecrawl-skills）
役割	ウェブ操作を実行する	エージェントに使い方を指示する
たとえ	手	頭脳
例	deep_research(query, iterations=3)	「3回調査し、各回の後に不足点を確認し、すべてに引用を付ける」
必須か？	はい（エンジン）	いいえ（ただし、調査品質の向上に推奨）

クイックセットアップ：

# 1. Install the tools (you already have this)
uvx pyrecrawl@latest

# 2. Add the research skill to your project
git clone https://github.com/SanggonBoy/pyrecrawl-skills.git /tmp/pyrecrawl-skills
cp /tmp/pyrecrawl-skills/pyrecrawl-research/SKILL.md ./CLAUDE.md  # or .cursorrules / AGENTS.md

スキルなし： エージェントは強力なツールを持ちますが、使い方はその場で工夫します。 スキルあり： エージェントは、ハルシネーション対策のガードレールを備えた、実証済みの調査プロトコルに従います。

---

📚 手動設定（pyrecrawl install が環境に合わない場合）

Claude Desktop

設定ファイル

• Linux：~/.config/Claude/claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%AppData%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pyrecrawl": {
      "command": "uvx",
      "args": ["--from", "pyrecrawl", "pyrecrawl", "serve"]
    }
  }
}

Claude Code

設定ファイル：プロジェクト単位の .mcp.json

{
  "mcpServers": {
    "pyrecrawl": {
      "command": "uvx",
      "args": ["--from", "pyrecrawl", "pyrecrawl", "serve"]
    }
  }
}

Cursor

設定ファイル：~/.cursor/mcp.json

{
  "mcpServers": {
    "pyrecrawl": {
      "command": "uvx",
      "args": ["--from", "pyrecrawl", "pyrecrawl", "serve"]
    }
  }
}

VS Code / Copilot

設定ファイル：プロジェクト単位の .vscode/mcp.json

{
  "servers": {
    "pyrecrawl": {
      "command": "uvx",
      "args": ["--from", "pyrecrawl", "pyrecrawl", "serve"],
      "type": "stdio"
    }
  }
}

Codex CLI

設定ファイル：~/.codex/config.toml

[mcp_servers.pyrecrawl]
command = "uvx"
args = ["--from", "pyrecrawl", "pyrecrawl", "serve"]

OpenCode

設定ファイル：~/.config/opencode/opencode.json

{
  "mcp": {
    "pyrecrawl": {
      "type": "local",
      "command": ["uvx", "--from", "pyrecrawl", "pyrecrawl", "serve"],
      "enabled": true
    }
  }
}

Hermes

設定ファイル

• Linux/macOS：~/.hermes/config.yaml
• Windows：%LocalAppData%\hermes\config.yaml

mcp_servers:
  pyrecrawl:
    command: uvx
    args:
      - --from
      - pyrecrawl
      - pyrecrawl
      - serve
    enabled: true

Windows に関する注意： uvx が PATH に含まれている必要があります。含まれていない場合は、uvx.exe のフルパスを使用してください（例：C:\Users\<you>\AppData\Local\hermes\bin\uvx.exe）。

---

🧠 ラダーの選択方法

PyreCrawl は各リクエストを 3 つのティアで処理し、LLM ですぐに利用できる結果を返した最初のティアで処理を終了します。

項目	高速ティア	ステルスティア	ディープティア
静的 HTML ページ	✅ 約200ms	—	—
Cloudflare で保護されたページ	❌	✅ Turnstile ソルバー	—
JS を多用する SPA	❌	✅ 実際の Chromium	—
ライブ DOM データ（入力欄の .value、JS の状態）	❌	✅ js パラメーター	—
LLM 対応の Markdown と引用	—	—	✅ BM25、fit-markdown
構造化抽出（CSS スキーマ）	—	—	✅
ディープクロール（BFS/DFS/BestFirst）	—	—	✅ 適応型

エージェントが選択する必要はありません。prefer="auto" が毎回自動で処理します。

js と wait_for によるライブ DOM データ

サイトによっては、必要なデータが DOM の プロパティ（例：XHR の後に JS が書き込む <input> の .value）に保持され、シリアル化された HTML には表示されないことがあります。scrape ツールでは、この用途に特化した 2 つのステルスティアのパラメーターを使用できます。

{
  "url": "https://temp-mail.org/id",
  "prefer": "stealth",
  "wait_for": "document.getElementById('mail').value.includes('@')",
  "js": "document.getElementById('mail').value"
}

• wait_for — 真になるまでポーリングする JS の述語式です（timeout による上限があります）。非同期で到着するデータには、時間を推測して待機する代わりに使用してください。
• js — ページの読み込みが落ち着いた後に 1 回評価される JS の式です。値は meta.js_result に返されます。エラーは meta.js_error に記録されます（ページの結果は引き続き返され、クラッシュすることはありません）。

---

📊 Firecrawl（ホステッド版）との比較

	Firecrawl	PyreCrawl
費用	月 1,000 件まで無料、その後は月額 $16～333	無料、セルフホスト可能
ローカル LLM のサポート	❌	✅ Ollama／任意の LLM
Cloudflare の回避	✅（Fire-Engine、有料）	✅（無料、標準搭載）
Markdown と BM25	✅	✅
セルフホスト	❌	✅
学術論文の検索	❌	✅ arXiv + Crossref（search_papers）
ホステッド検索 API	✅ /search	⚠️ DuckDuckGo HTML + arXiv/Crossref（キー不要）

---

🔧 開発

git clone https://github.com/SanggonBoy/PyreCrawl.git
cd PyreCrawl
uv venv --python 3.12 .venv
source .venv/Scripts/activate  # Windows; or .venv/bin/activate on macOS/Linux
uv pip install -e ".[dev]"
python -m playwright install chromium
scrapling install

テストの実行

python scripts/selfcheck.py        # real-network smoke test (13 tools + engines)
python scripts/probe_stdio.py      # stdio JSON-RPC probe
python scripts/test_ladder_bug.py  # SPA-shell ladder escalation regression
python scripts/test_js_eval.py     # stealth js/wait_for params regression
python scripts/test_scope_selector.py  # crawl css_selector/max_depth wiring
python scripts/test_link_harvest.py    # map/BFS link purity regression

---

📦 公開

メンテナーのみ：

git tag vX.Y.Z
git push origin vX.Y.Z

GitHub Actions が trusted publishing を使用してビルドし、PyPI にアップロードします。

---

🔔 最新情報を確認する

PyreCrawl は起動のたびに PyPI を確認し、最新バージョンを報告します。MCP エージェントは health() ツールの応答を通じてこれを自動的に認識し、インラインで通知できます。

手動で確認するには：

pyrecrawl version

アップグレードするには：

pyrecrawl update   # runs: uv tool upgrade pyrecrawl

新しいリリースの通知を受け取る： GitHub リポジトリで Watch → Releases only をクリックすると、新しいバージョンが公開されたときにメール通知が届きます。

---

メモ

PyreCrawl はサーバー起動時に、24 時間に 1 回、匿名の使用状況 ping を送信します。送信内容とオプトアウト方法については、プライバシーをご覧ください。

🔒 プライバシー — 匿名の使用状況 ping

PyreCrawl は実際のユーザー数（DAU/MAU）をダウンロード数ではなく集計できるよう、MCP サーバーの起動時に 24 時間に 1 回、少量の匿名 ping を送信します。

送信される情報（4 項目、約 100 バイト）	送信されない情報
ハッシュ化されたマシン ID（ホスト名と MAC の SHA-256 — 元に戻せません）	IP アドレス（保存されません）
PyreCrawl のバージョン	スクレイピングする URL
Python のバージョン	ページのコンテンツや検索クエリ
OS の種類（windows／linux／darwin）	その他すべて

クライアントコード：src/pyrecrawl/telemetry.py（約 90 行、標準ライブラリのみ） · 収集先：workers/telemetry/ — セルフホスト可能な Cloudflare Worker + D1。サードパーティの分析サービスは使用しません。

いつでもオプトアウトできます：

export PYRECRAWL_NO_TELEMETRY=1   # or the industry-standard DO_NOT_TRACK=1

---

📜 アンインストール

# Remove from all agent configs
pyrecrawl uninstall

# Remove the package
uv tool uninstall pyrecrawl

---

🛡️ ライセンス

MIT — LICENSE をご覧ください。