> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Firecrawl MCP のツールとオペレーション

> Firecrawl MCP で利用できるツール、オペレーションの動作、エラーハンドリング。

<div id="available-tools">
  ## 利用可能なツール
</div>

<div id="1-scrape-tool-firecrawl_scrape">
  ### 1. Scrape ツール (`firecrawl_scrape`)
</div>

高度なオプションを使用して、1 つの URL からコンテンツをスクレイピングします。

```json theme={null}
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["markdown"],
    "onlyMainContent": true,
    "waitFor": 1000,
    "mobile": false,
    "includeTags": ["article", "main"],
    "excludeTags": ["nav", "footer"],
    "skipTlsVerification": false
  }
}
```

個人を特定できる情報をマスキングするには、スクレイピングツールの引数に`redactPII`を含めます。

```json theme={null}
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/contact",
    "formats": ["markdown"],
    "redactPII": true
  }
}
```

<div id="2-map-tool-firecrawl_map">
  ### 2. Map ツール (`firecrawl_map`)
</div>

Web サイトをマッピングし、サイト内のインデックス済み URL をすべて検出します。

```json theme={null}
{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com",
    "search": "blog",
    "sitemap": "include",
    "includeSubdomains": false,
    "limit": 100,
    "ignoreQueryParameters": true
  }
}
```

<div id="map-tool-options">
  #### Map Tool のオプション:
</div>

* `url`: マッピング対象の Web サイトのベース URL
* `search`: URL を絞り込むための任意の検索語
* `sitemap`: サイトマップの使用方法を指定 - "include"、"skip"、または "only"
* `includeSubdomains`: マッピングにサブドメインを含めるかどうか
* `limit`: 返す URL の最大数
* `ignoreQueryParameters`: マッピング時にクエリパラメータを無視するかどうか

**最適な用途:** スクレイピング対象を決める前に Web サイト内の URL を見つける、または Web サイト内の特定セクションを探す。
**戻り値:** サイト内で見つかった URL の配列。

<div id="3-search-tool-firecrawl_search">
  ### 3. Search Tool (`firecrawl_search`)
</div>

ウェブを検索し、必要に応じて検索結果からコンテンツを抽出します。

```json theme={null}
{
  "name": "firecrawl_search",
  "arguments": {
    "query": "your search query",
    "limit": 5,
    "location": "United States",
    "tbs": "qdr:m",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}
```

<div id="search-tool-options">
  #### Search Tool のオプション:
</div>

* `query`: 検索クエリ文字列 (必須)
* `limit`: 返す検索結果の最大数
* `location`: 検索結果の地理的ロケーション
* `tbs`: 期間ベースの検索フィルター (例: 過去1日は `qdr:d`、過去1週間は `qdr:w`、過去1か月は `qdr:m`)
* `filter`: 追加の検索フィルター
* `sources`: 検索対象のソースタイプの配列 (`web`、`images`、`news`)
* `scrapeOptions`: 検索結果ページのスクレイピングオプション
* `enterprise`: エンタープライズオプションの配列 (`default`、`anon`、`zdr`)

<div id="4-parse-tool-firecrawl_parse">
  ### 4. Parse Tool (`firecrawl_parse`)
</div>

PDF、DOCX、XLSX、HTML ドキュメントなどのローカルファイルを、クリーンで LLM 対応のデータに解析します。

```json theme={null}
{
  "name": "firecrawl_parse",
  "arguments": {
    "filePath": "/absolute/path/to/report.pdf",
    "formats": ["markdown"]
  }
}
```

`FIRECRAWL_API_URL` を使用して Firecrawl API インスタンスに対し Firecrawl MCP をローカルで実行する場合、MCP Server は `filePath` を直接読み取り、ファイルのバイト列を `/v2/parse` に送信できます。

リモートのホスト型 MCP Server を使用する場合、ホスト型サーバーはお使いのマシン上のファイルを読み取れません。その場合、`firecrawl_parse` はリモートのキーなし URL でも機能する、2 段階の受け渡しを使用します。

1. `filePath` を指定して `firecrawl_parse` を呼び出します。ツールは、あらかじめ入力されたアップロードコマンドと、`uploadRef` を含む `nextToolCall` を返します。
2. ファイルを読み取れるマシンでアップロードコマンドを実行し、返された `uploadRef` を指定して再度 `firecrawl_parse` を呼び出します。

アップロードコマンドは、短時間のみ有効な署名付きアップロード先にファイルのバイト列を送信します。Firecrawl APIキーは含まれません。

<div id="parse-tool-options">
  #### Parse Tool のオプション:
</div>

* `filePath`: 解析するファイルのローカルパスです。最初の呼び出しで使用します。
* `uploadRef`: 最初のホスト型 MCP 呼び出しで返される参照です。アップロード成功後の 2 回目の呼び出しで使用します。
* `formats`: 出力フォーマットです。デフォルトは `markdown` です。
* `parsers`: PDF 解析オプションなど、パーサーを制御します。
* `contentType`: 任意で指定できるファイルの MIME タイプのオーバーライドです。
* `declaredSizeBytes`: 任意のファイルサイズの目安です。ファイルサイズは 50 MB までです。

**最適な用途:** 公開 URL から利用できないローカルまたは非公開のドキュメント。

**推奨されない用途:** 公開ドキュメントの URL。代わりに `firecrawl_scrape` を使用してください。URL 上のドキュメントを検出して解析します。

<div id="5-crawl-tool-firecrawl_crawl">
  ### 5. クロールツール (`firecrawl_crawl`)
</div>

高度なオプションを指定して、非同期クロールを開始します。

```json theme={null}
{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://example.com",
    "maxDiscoveryDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}
```

<div id="6-check-crawl-status-firecrawl_check_crawl_status">
  ### 6. クロールのステータスを確認 (`firecrawl_check_crawl_status`)
</div>

クロールジョブのステータスを確認します。

```json theme={null}
{
  "name": "firecrawl_check_crawl_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**戻り値:** クロールジョブのステータスと進行状況。利用可能な場合は結果も含まれます。

<div id="7-extract-tool-firecrawl_extract">
  ### 7. Extract Tool (`firecrawl_extract`)
</div>

LLMを活用してWebページから構造化情報を抽出します。クラウドAIとセルフホスト型LLMの両方による抽出に対応しています。

```json theme={null}
{
  "name": "firecrawl_extract",
  "arguments": {
    "urls": ["https://example.com/page1", "https://example.com/page2"],
    "prompt": "Extract product information including name, price, and description",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "price": { "type": "number" },
        "description": { "type": "string" }
      },
      "required": ["name", "price"]
    },
    "allowExternalLinks": false,
    "enableWebSearch": false,
    "includeSubdomains": false
  }
}
```

レスポンスの例：

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": {
        "name": "Example Product",
        "price": 99.99,
        "description": "This is an example product description"
      }
    }
  ],
  "isError": false
}
```

<div id="extract-tool-options">
  #### Extract Tool のオプション:
</div>

* `urls`: 情報を抽出する URL の配列
* `prompt`: LLM による抽出用のカスタムプロンプト
* `schema`: 構造化データ抽出用の JSON スキーマ
* `allowExternalLinks`: 外部リンクからの抽出を許可
* `enableWebSearch`: 追加のコンテキストを得るためにウェブ検索を有効化
* `includeSubdomains`: 抽出対象にサブドメインを含める

セルフホスト型インスタンスを使用する場合、設定済みの LLM が抽出に使用されます。クラウド API では、Firecrawl が管理する LLM サービスが使用されます。

<div id="8-agent-tool-firecrawl_agent">
  ### 8. エージェント Tool (`firecrawl_agent`)
</div>

クエリに基づいてインターネットを自律的にブラウジングし、情報を検索してページを移動し、構造化データを抽出するWebリサーチエージェントです。非同期で実行され、すぐにジョブIDが返されます。完了後に結果を取得するには、`firecrawl_agent_status`をポーリングします。

```json theme={null}
{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Find the top 5 AI startups founded in 2024 and their funding amounts",
    "schema": {
      "type": "object",
      "properties": {
        "startups": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "funding": { "type": "string" },
              "founded": { "type": "string" }
            }
          }
        }
      }
    }
  }
}
```

エージェントに重点的に処理させる特定のURLを指定することもできます：

```json theme={null}
{
  "name": "firecrawl_agent",
  "arguments": {
    "urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    "prompt": "Compare the features and pricing information from these pages"
  }
}
```

<div id="agent-tool-options">
  #### エージェント Tool のオプション:
</div>

* `prompt`: 必要なデータを自然言語で記述します (必須、最大10,000文字)
* `urls`: エージェント が特定のページに集中できるようにする任意の URL 配列
* `schema`: 構造化された出力のための任意の JSON schema

**最適な用途:** 正確な URL が不明な複雑なリサーチタスク、複数のソースからのデータ収集、Web 上に散在する情報の検索、通常のスクレイピングでは失敗する JavaScript を多用した SPA からのデータ抽出。

**戻り値:** ステータス確認用の job ID。結果をポーリングするには `firecrawl_agent_status` を使用します。

<div id="9-check-agent-status-firecrawl_agent_status">
  ### 9. エージェント Status の確認 (`firecrawl_agent_status`)
</div>

エージェント job の status を確認し、完了したら結果を取得します。15～30 秒ごとにポーリングし、request が失敗したと判断する前に、少なくとも 2～3 分間はポーリングを続けてください。

```json theme={null}
{
  "name": "firecrawl_agent_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

<div id="agent-status-options">
  #### エージェント Status のオプション:
</div>

* `id`: `firecrawl_agent` が返す エージェント job ID (必須)

**ステータス:**

* `processing`: エージェント はまだリサーチ中です -- ポーリングを続けてください
* `completed`: リサーチが完了しました -- レスポンスに抽出データが含まれます
* `failed`: エラーが発生しました

**戻り値:** エージェント job のステータス、進捗状況、結果 (完了している場合) 。

<div id="10-interact-with-a-page-firecrawl_interact">
  ### 10. ページを操作する (`firecrawl_interact`)
</div>

ライブのブラウザセッションでページを操作します。ボタンのクリック、フォームへの入力、動的コンテンツの抽出、より深いページへの移動などが可能です。

ターゲットの指定方法は2つあります。

* `url` を渡すと、1回のMCP呼び出しで新しいページを開いて操作できます。
* 以前の `firecrawl_scrape` 呼び出しで取得した `scrapeId` を渡すと、すでに読み込まれているページを再利用できます。

`url` と `scrapeId` を同時に渡さないでください。`prompt` または `code` のいずれかを指定してください。`scrapeOptions` は `url` モードでのみ使用できます。

**URLモードの例：**

```json theme={null}
{
  "name": "firecrawl_interact",
  "arguments": {
    "url": "https://example.com/products",
    "prompt": "Click on the first product and tell me its price"
  }
}
```

**スクレイピングの再利用の例:**

```json theme={null}
{
  "name": "firecrawl_interact",
  "arguments": {
    "scrapeId": "scrape-id-from-previous-scrape",
    "prompt": "Click the Sign In button"
  }
}
```

<div id="interact-tool-options">
  #### Interact ツールのオプション:
</div>

* `url`: 操作するページ。セッションを開きます。これまたは `scrapeId` を使用します。
* `scrapeId`: 以前の `firecrawl_scrape` 呼び出しで取得したスクレイピングジョブ ID。これまたは `url` を使用します。
* `prompt`: 実行する操作を説明する自然言語の指示。`prompt` または `code` を指定します。
* `code`: ブラウザセッションで実行するコード。`code` または `prompt` を指定します。
* `language`: `bash`、`python`、または `node` (任意。デフォルトは `node`。`code` でのみ使用) 。
* `timeout`: 実行タイムアウト (秒単位) 。1～300 (任意。デフォルトは30) 。
* `scrapeOptions`: `url` モードでのみ使用する任意のスクレイピング制御。

**最適な用途:** 単一ページ上で複数ステップのワークフローを実行する場合 — サイト内検索、検索結果のクリック、フォーム入力、操作が必要なデータの抽出。

**戻り値:** 出力とライブビュー URL を含む操作結果。

<div id="11-stop-interact-session-firecrawl_interact_stop">
  ### 11. Interact セッションを停止 (`firecrawl_interact_stop`)
</div>

スクレイピングしたページの Interact セッションを停止します。操作が完了したら、リソースを解放するためにこのツールを呼び出してください。

```json theme={null}
{
  "name": "firecrawl_interact_stop",
  "arguments": {
    "scrapeId": "scrape-id-from-previous-scrape"
  }
}
```

<div id="interact-stop-options">
  #### Interact 停止オプション:
</div>

* `scrapeId`: 停止するセッションのスクレイピング ID (必須)

**戻り値:** セッションが停止したことの確認。

<div id="logging-system">
  ## ロギングシステム
</div>

サーバーには、包括的なログ機能が含まれています。

* オペレーションのステータスと進行状況
* パフォーマンス指標
* クレジット使用量の監視
* レート制限の追跡
* エラー状態

ログメッセージの例：

```
[INFO] Firecrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[INFO] Starting crawl for URL: https://example.com
[WARNING] Credit usage has reached warning threshold
[ERROR] Rate limit exceeded, retrying in 2s...
```

<div id="error-handling">
  ## エラーハンドリング
</div>

サーバーは堅牢なエラーハンドリング機能を提供します。

* 一時的なエラーの自動再試行
* バックオフによるレート制限への対応
* 詳細なエラーメッセージ
* クレジット使用量に関する警告
* ネットワーク障害への耐性

エラーレスポンスの例：

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
    }
  ],
  "isError": true
}
```