> ## 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 tools and operations

> Available tools, operational behavior, and error handling for Firecrawl MCP.

## Available Tools

### 1. Scrape Tool (`firecrawl_scrape`)

Scrape content from a single URL with advanced options.

```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
  }
}
```

To redact personally identifiable information, include `redactPII` in the scrape tool arguments.

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

### 2. Map Tool (`firecrawl_map`)

Map a website to discover all indexed URLs on the site.

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

#### Map Tool Options:

* `url`: The base URL of the website to map
* `search`: Optional search term to filter URLs
* `sitemap`: Control sitemap usage - "include", "skip", or "only"
* `includeSubdomains`: Whether to include subdomains in the mapping
* `limit`: Maximum number of URLs to return
* `ignoreQueryParameters`: Whether to ignore query parameters when mapping

**Best for:** Discovering URLs on a website before deciding what to scrape; finding specific sections of a website.
**Returns:** Array of URLs found on the site.

### 3. Search Tool (`firecrawl_search`)

Search the web and optionally extract content from search results.

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

#### Search Tool Options:

* `query`: The search query string (required)
* `limit`: Maximum number of results to return
* `location`: Geographic location for search results
* `tbs`: Time-based search filter (e.g., `qdr:d` for past day, `qdr:w` for past week, `qdr:m` for past month)
* `filter`: Additional search filter
* `sources`: Array of source types to search (`web`, `images`, `news`)
* `scrapeOptions`: Options for scraping search result pages
* `enterprise`: Array of enterprise options (`default`, `anon`, `zdr`)

### 4. Parse Tool (`firecrawl_parse`)

Parse a local file such as a PDF, DOCX, XLSX, or HTML document into clean, LLM-ready data.

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

When you run Firecrawl MCP locally against a Firecrawl API instance with `FIRECRAWL_API_URL`, the MCP server can read `filePath` directly and sends the file bytes to `/v2/parse`.

When you use the remote hosted MCP server, the hosted server cannot read files from your machine. In that case `firecrawl_parse` uses a two-step handoff that also works on the remote keyless URL:

1. Call `firecrawl_parse` with `filePath`. The tool returns a pre-filled upload command and a `nextToolCall` containing an `uploadRef`.
2. Run the upload command on the machine that can read the file, then call `firecrawl_parse` again with the returned `uploadRef`.

The upload command sends the file bytes to a short-lived signed upload target. It does not include your Firecrawl API key.

#### Parse Tool Options:

* `filePath`: Local path to the file you want to parse. Use this for the first call.
* `uploadRef`: Reference returned by the first hosted-MCP call. Use this for the second call after the upload succeeds.
* `formats`: Output formats. Defaults to `markdown`.
* `parsers`: Parser controls, such as PDF parsing options.
* `contentType`: Optional file MIME type override.
* `declaredSizeBytes`: Optional file size hint. Files are limited to 50 MB.

**Best for:** Local or non-public documents that are not available at a public URL.

**Not recommended for:** Public document URLs. Use `firecrawl_scrape` instead; it will detect and parse documents from URLs.

### 5. Crawl Tool (`firecrawl_crawl`)

Start an asynchronous crawl with advanced options.

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

### 6. Check Crawl Status (`firecrawl_check_crawl_status`)

Check the status of a crawl job.

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

**Returns:** Status and progress of the crawl job, including results if available.

### 7. Extract Tool (`firecrawl_extract`)

Extract structured information from web pages using LLM capabilities. Supports both cloud AI and self-hosted LLM extraction.

```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
  }
}
```

Example response:

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

#### Extract Tool Options:

* `urls`: Array of URLs to extract information from
* `prompt`: Custom prompt for the LLM extraction
* `schema`: JSON schema for structured data extraction
* `allowExternalLinks`: Allow extraction from external links
* `enableWebSearch`: Enable web search for additional context
* `includeSubdomains`: Include subdomains in extraction

When using a self-hosted instance, the extraction will use your configured LLM. For cloud API, it uses Firecrawl's managed LLM service.

### 8. Agent Tool (`firecrawl_agent`)

Autonomous web research agent that independently browses the internet, searches for information, navigates through pages, and extracts structured data based on your query. This runs asynchronously -- it returns a job ID immediately, and you poll `firecrawl_agent_status` to check when complete and retrieve results.

```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" }
            }
          }
        }
      }
    }
  }
}
```

You can also provide specific URLs for the agent to focus on:

```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"
  }
}
```

#### Agent Tool Options:

* `prompt`: Natural language description of the data you want (required, max 10,000 characters)
* `urls`: Optional array of URLs to focus the agent on specific pages
* `schema`: Optional JSON schema for structured output

**Best for:** Complex research tasks where you don't know the exact URLs; multi-source data gathering; finding information scattered across the web; extracting data from JavaScript-heavy SPAs that fail with regular scrape.

**Returns:** Job ID for status checking. Use `firecrawl_agent_status` to poll for results.

### 9. Check Agent Status (`firecrawl_agent_status`)

Check the status of an agent job and retrieve results when complete. Poll every 15-30 seconds and keep polling for at least 2-3 minutes before considering the request failed.

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

#### Agent Status Options:

* `id`: The agent job ID returned by `firecrawl_agent` (required)

**Possible statuses:**

* `processing`: Agent is still researching -- keep polling
* `completed`: Research finished -- response includes the extracted data
* `failed`: An error occurred

**Returns:** Status, progress, and results (if completed) of the agent job.

### 10. Interact with a Page (`firecrawl_interact`)

Interact with a page in a live browser session: click buttons, fill forms, extract dynamic content, or navigate deeper.

Use one of two targeting modes:

* Pass `url` to open and interact with a fresh page in one MCP call.
* Pass `scrapeId` from a previous `firecrawl_scrape` call to reuse the already-loaded page.

Do not pass both `url` and `scrapeId`. Provide either `prompt` or `code`. `scrapeOptions` can only be used with `url` mode.

**URL mode example:**

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

**Scrape reuse example:**

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

#### Interact Tool Options:

* `url`: Page to interact with; opens the session for you. Use this or `scrapeId`.
* `scrapeId`: Scrape job ID from a previous `firecrawl_scrape` call. Use this or `url`.
* `prompt`: Natural language instruction describing the action to take. Provide `prompt` or `code`.
* `code`: Code to execute in the browser session. Provide `code` or `prompt`.
* `language`: `bash`, `python`, or `node` (optional, defaults to `node`, only used with `code`).
* `timeout`: Execution timeout in seconds, 1–300 (optional, defaults to 30).
* `scrapeOptions`: Optional scrape controls used only with `url` mode.

**Best for:** Multi-step workflows on a single page — searching a site, clicking through results, filling forms, extracting data that requires interaction.

**Returns:** Interaction result including output and live view URLs.

### 11. Stop Interact Session (`firecrawl_interact_stop`)

Stop an interact session for a scraped page. Call this when you are done interacting to free resources.

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

#### Interact Stop Options:

* `scrapeId`: The scrape ID for the session to stop (required)

**Returns:** Confirmation that the session has been stopped.

## Logging System

The server includes comprehensive logging:

* Operation status and progress
* Performance metrics
* Credit usage monitoring
* Rate limit tracking
* Error conditions

Example log messages:

```
[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...
```

## Error Handling

The server provides robust error handling:

* Automatic retries for transient errors
* Rate limit handling with backoff
* Detailed error messages
* Credit usage warnings
* Network resilience

Example error response:

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