crawl

クロールスキル

複数のページからコンテンツを抽出するために、ウェブサイトをクロールします。ドキュメント、ナレッジベース、サイト全体のコンテンツ抽出に最適です。

認証

このスクリプトは Tavily MCP サーバー経由で OAuth を使用します。手動での設定は不要です。初回実行時に、次の処理が行われます。

1. ~/.mcp-auth/ に既存のトークンがあるか確認します
2. トークンが見つからない場合は、OAuth 認証のためにブラウザーを自動的に開きます

注： 既存の Tavily アカウントが必要です。OAuth フローではログインのみがサポートされており、アカウントの作成はできません。アカウントをお持ちでない場合は、まず tavily.com で登録してください。

代替方法：API キー

API キーを使用する場合は、https://tavily.com で取得し、~/.claude/settings.json に追加してください。

{
  "env": {
    "TAVILY_API_KEY": "tvly-your-api-key-here"
  }
}

クイックスタート

スクリプトを使用する

./scripts/crawl.sh '<json>' [output_dir]

例：

# Basic crawl
./scripts/crawl.sh '{"url": "https://docs.example.com"}'

# Deeper crawl with limits
./scripts/crawl.sh '{"url": "https://docs.example.com", "max_depth": 2, "limit": 50}'

# Save to files
./scripts/crawl.sh '{"url": "https://docs.example.com", "max_depth": 2}' ./docs

# Focused crawl with path filters
./scripts/crawl.sh '{"url": "https://example.com", "max_depth": 2, "select_paths": ["/docs/.*", "/api/.*"], "exclude_paths": ["/blog/.*"]}'

# With semantic instructions (for agentic use)
./scripts/crawl.sh '{"url": "https://docs.example.com", "instructions": "Find API documentation", "chunks_per_source": 3}'

output_dir を指定すると、クロールしたページがそれぞれ個別の Markdown ファイルとして保存されます。

基本的なクロール

curl --request POST \
  --url https://api.tavily.com/crawl \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://docs.example.com",
    "max_depth": 1,
    "limit": 20
  }'

指示を指定した重点的なクロール

curl --request POST \
  --url https://api.tavily.com/crawl \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://docs.example.com",
    "max_depth": 2,
    "instructions": "Find API documentation and code examples",
    "chunks_per_source": 3,
    "select_paths": ["/docs/.*", "/api/.*"]
  }'

API リファレンス

エンドポイント

POST https://api.tavily.com/crawl

ヘッダー

ヘッダー	値
Authorization	Bearer <TAVILY_API_KEY>
Content-Type	application/json

リクエストボディ

フィールド	型	デフォルト	説明
url	string	必須	クロールを開始するルート URL
max_depth	integer	1	クロールする深さのレベル（1～5）
max_breadth	integer	20	ページあたりのリンク数
limit	integer	50	ページ数の上限
instructions	string	null	対象を絞り込むための自然言語による指示
chunks_per_source	integer	3	ページあたりのチャンク数（1～5、instructions が必要）
extract_depth	string	"basic"	basic または advanced
format	string	"markdown"	markdown または text
select_paths	array	null	対象に含める正規表現パターン
exclude_paths	array	null	除外する正規表現パターン
allow_external	boolean	true	外部ドメインへのリンクを含めるかどうか
timeout	float	150	最大待機時間（10～150 秒）

レスポンス形式

{
  "base_url": "https://docs.example.com",
  "results": [
    {
      "url": "https://docs.example.com/page",
      "raw_content": "# Page Title\n\nContent..."
    }
  ],
  "response_time": 12.5
}

深さとパフォーマンス

深さ	ページ数の目安	所要時間
1	10～50	数秒
2	50～500	数分
3	500～5000	数分以上

まず max_depth=1 から始め、必要な場合にのみ増やしてください。

コンテキスト用のクロールとデータ収集用のクロール

エージェント用途（結果をコンテキストに渡す場合）： 常に instructions と chunks_per_source を使用してください。ページ全体ではなく、関連するチャンクだけが返されるため、コンテキストウィンドウが肥大化するのを防げます。

データ収集用途（ファイルに保存する場合）： ページ全体のコンテンツを取得するには、chunks_per_source を省略してください。

例

コンテキスト用：エージェントによる調査（推奨）

クロール結果を LLM のコンテキストに渡す場合に使用します。

curl --request POST \
  --url https://api.tavily.com/crawl \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://docs.example.com",
    "max_depth": 2,
    "instructions": "Find API documentation and authentication guides",
    "chunks_per_source": 3
  }'

ページごとに最も関連性の高いチャンクのみが返されます（各チャンクは最大 500 文字）。コンテキストに収まり、過剰な情報であふれることもありません。

コンテキスト用：対象を絞った技術ドキュメント

curl --request POST \
  --url https://api.tavily.com/crawl \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com",
    "max_depth": 2,
    "instructions": "Find all documentation about authentication and security",
    "chunks_per_source": 3,
    "select_paths": ["/docs/.*", "/api/.*"]
  }'

データ収集用：ページ全体のアーカイブ

後で処理するためにコンテンツをファイルに保存する場合に使用します。

curl --request POST \
  --url https://api.tavily.com/crawl \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/blog",
    "max_depth": 2,
    "max_breadth": 50,
    "select_paths": ["/blog/.*"],
    "exclude_paths": ["/blog/tag/.*", "/blog/category/.*"]
  }'

ページ全体のコンテンツが返されます。スクリプトの output_dir を指定して、Markdown ファイルとして保存してください。

Map API（URL の検出）

コンテンツではなく URL だけが必要な場合は、crawl の代わりに map を使用します。

curl --request POST \
  --url https://api.tavily.com/map \
  --header "Authorization: Bearer $TAVILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://docs.example.com",
    "max_depth": 2,
    "instructions": "Find all API docs and guides"
  }'

URL のみが返されます（crawl より高速です）。

{
  "base_url": "https://docs.example.com",
  "results": [
    "https://docs.example.com/api/auth",
    "https://docs.example.com/guides/quickstart"
  ]
}

ヒント

• エージェントワークフローでは常に chunks_per_source を使用してください。結果を LLM に渡す際のコンテキストの肥大化を防ぎます
• chunks_per_source はデータ収集時のみ省略してください。ページ全体をファイルに保存する場合に使用します
• 控えめな設定から始めてください（max_depth=1、limit=20）。必要に応じて規模を拡大します
• パスパターンを使用して、関連するセクションに対象を絞ります
• 本格的にクロールする前に Map を使用して、サイトの構造を把握します
• 暴走したクロールを防ぐため、必ず limit を設定してください