### Development Setup Commands

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Provides essential commands for setting up and running the Firecrawl MCP Server development environment, including dependency installation, building, and testing.

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test
```

--------------------------------

### Production Configuration Example

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Example of setting environment variables for production deployment and running the Firecrawl MCP server.

```bash
export FIRECRAWL_API_KEY=fc-abc123
export FIRECRAWL_RETRY_MAX_ATTEMPTS=5
export FIRECRAWL_RETRY_INITIAL_DELAY=2000
export FIRECRAWL_RETRY_MAX_DELAY=30000
export FIRECRAWL_RETRY_BACKOFF_FACTOR=3
export FIRECRAWL_CREDIT_WARNING_THRESHOLD=2000
export FIRECRAWL_CREDIT_CRITICAL_THRESHOLD=500
npx -y firecrawl-mcp
```

--------------------------------

### Starting and Testing the Cloud Server

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Commands to start the cloud server and test its health endpoint using curl.

```bash
# Start cloud server
npm run start:cloud
# or: CLOUD_SERVICE=true node dist/index.js

# Test health endpoint
curl http://localhost:3000/health
# → ok
```

--------------------------------

### Manually Install Firecrawl MCP Server

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Installs the Firecrawl MCP server globally using npm. Ensure you have Node.js and npm installed.

```bash
npm install -g firecrawl-mcp
```

--------------------------------

### Install Firecrawl MCP Server via Smithery

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Installs the Firecrawl MCP server for Claude Desktop using the Smithery CLI. This is a legacy installation method.

```bash
npx -y @smithery/cli install @mendableai/mcp-server-firecrawl --client claude
```

--------------------------------

### Development and Build Commands

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Common commands for installing dependencies, building the project, running tests, linting, formatting, and publishing.

```bash
# Install dependencies
npm install

# Build TypeScript → dist/
npm run build

# Run unit tests
npm test

# Lint
npm run lint
npm run lint:fix

# Format with Prettier
npm run format

# Publish to npm
npm run publish-prod       # npm publish (latest tag)
npm run publish-beta       # npm publish --tag beta
```

--------------------------------

### Start Firecrawl MCP Server for Local Development

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md

Start the local server, which defaults to the V2 implementation. You can also enable SSE local or HTTP streamable server modes using environment variables.

```bash
# Start local server (V2 by default)
npm start

# Start SSE local server
SSE_LOCAL=true npm start

# Start HTTP streamable server
HTTP_STREAMABLE_SERVER=true npm start
```

--------------------------------

### Install Firecrawl MCP in VS Code

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Use these buttons for one-click installation of the Firecrawl MCP server in VS Code. You will be prompted for your Firecrawl API key.

```json
{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Firecrawl API Key",
        "password": true
      }
    ],
    "servers": {
      "firecrawl": {
        "command": "npx",
        "args": ["-y", "firecrawl-mcp"],
        "env": {
          "FIRECRAWL_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}
```

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Firecrawl API Key",
      "password": true
    }
  ],
  "servers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "${input:apiKey}"
      }
    }
  }
}
```

--------------------------------

### Start Firecrawl MCP Server in Cloud Mode

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md

To start the server with versioned cloud endpoints enabled, use this npm command. Ensure the CLOUD_SERVICE environment variable is set to true.

```bash
# Start versioned cloud server
npm run start:cloud
```

--------------------------------

### Run Firecrawl MCP Server with npx

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Installs and runs the Firecrawl MCP server using npx. Requires setting the FIRECRAWL_API_KEY environment variable.

```bash
env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp
```

--------------------------------

### Example Log Messages

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Illustrates various log message types generated by the Firecrawl MCP Server, including informational, warning, and error messages.

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

--------------------------------

### Example Error Response

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Shows a typical error response structure from the Firecrawl MCP Server, indicating an error occurred and providing a descriptive message.

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

--------------------------------

### Start Batch Scrape Operation

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Initiates a batch scraping operation for a list of URLs, processing them in parallel with rate limiting. Returns a batch operation ID for status checking. Configure output formats and extraction schema within options.

```json
{
  "name": "firecrawl_batch_scrape",
  "arguments": {
    "urls": [
      "https://example.com/products/widget-a",
      "https://example.com/products/widget-b",
      "https://example.com/products/widget-c"
    ],
    "options": {
      "formats": ["json"],
      "jsonOptions": {
        "prompt": "Extract product name, price, and availability",
        "schema": {
          "type": "object",
          "properties": {
            "name":      { "type": "string" },
            "price":     { "type": "number" },
            "available": { "type": "boolean" }
          }
        }
      },
      "onlyMainContent": true
    }
  }
}
```

--------------------------------

### firecrawl_extract Tool Response

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

This is an example of the structured data returned by the `firecrawl_extract` tool, conforming to the provided schema.

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

--------------------------------

### Configure Firecrawl MCP Server for VS Code

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Configure the Firecrawl MCP server within VS Code's user settings. This setup allows for dynamic input of the API key.

```json
{
  "mcp": {
    "inputs": [
      { "type": "promptString", "id": "apiKey", "description": "Firecrawl API Key", "password": true }
    ],
    "servers": {
      "firecrawl": {
        "command": "npx",
        "args": ["-y", "firecrawl-mcp"],
        "env": { "FIRECRAWL_API_KEY": "${input:apiKey}" }
      }
    }
  }
}
```

--------------------------------

### Start Firecrawl MCP Server in Cloud Service Mode

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Launch the Firecrawl MCP Server in cloud service mode using a specific npm script. This mode is typically used with versioned endpoints.

```bash
npm run start:cloud   # CLOUD_SERVICE=true node dist/index.js
```

--------------------------------

### Initiate Firecrawl Crawl Job

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Start an asynchronous crawl job on a website to extract content from all pages. Best for comprehensive coverage of multiple related pages. Be cautious with 'maxDepth' and 'limit' to avoid token overflow and long processing times. Use 'allowExternalLinks' and 'deduplicateSimilarURLs' for control.

```json
{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://example.com/blog/*",
    "maxDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}
```

--------------------------------

### Scrape a URL to get a scrapeId

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Initiates a scrape operation for a given URL and specifies the desired output format. Requires a scrapeId for subsequent interactions.

```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/search",
    "formats": ["markdown"]
  }
}
```

--------------------------------

### firecrawl_crawl

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Starts an asynchronous multi-page crawl job, extracting content from all reachable pages within a domain. Returns a job ID for polling.

```APIDOC
## `firecrawl_crawl` — Crawl an Entire Site

Starts an asynchronous multi-page crawl job, extracting content from all reachable pages within a domain. Returns a job ID for polling. Use `includePaths`/`excludePaths` globs and `maxDiscoveryDepth`/`limit` to keep responses within token limits.

### Parameters

#### Arguments

- **url** (string) - Required - The starting URL to crawl.
- **maxDiscoveryDepth** (integer) - Optional - The maximum depth to discover new URLs.
- **limit** (integer) - Optional - The maximum number of pages to crawl.
- **allowExternalLinks** (boolean) - Optional - Whether to follow external links.
- **deduplicateSimilarURLs** (boolean) - Optional - Whether to deduplicate similar URLs.
- **sitemap** (string) - Optional - Whether to include sitemap URLs ('include' or 'exclude').
- **includePaths** (array) - Optional - Globs to include specific paths.
- **excludePaths** (array) - Optional - Globs to exclude specific paths.
- **prompt** (string) - Optional - A prompt to guide the content extraction.
- **webhook** (string) - Optional - A URL to send a notification when the crawl is complete.
- **webhookHeaders** (object) - Optional - Headers to include in the webhook notification.
- **scrapeOptions** (object) - Optional - Options for scraping content during the crawl.
  - **formats** (array) - Optional - The desired output formats for scraped content (e.g., `["markdown"]`).
  - **onlyMainContent** (boolean) - Optional - Whether to only scrape the main content of the page.

### Request Example

```json
{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://docs.example.com/guides",
    "maxDiscoveryDepth": 3,
    "limit": 50,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true,
    "sitemap": "include",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}
```

### Response Example

```json
{
  "content": [{ "type": "text", "text": "Started crawl ... job ID: 550e8400-e29b-41d4-a716-446655440000. Use firecrawl_check_crawl_status to check progress." }]
}
```
```

```APIDOC
## `firecrawl_check_crawl_status` — Check Crawl Status

Checks the status of an ongoing or completed crawl job.

### Parameters

#### Arguments

- **id** (string) - Required - The ID of the crawl job.

### Request Example

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

### Response Example

```json
{
  "status": "completed",
  "completed": 47,
  "total": 47,
  "data": [{ "markdown": "..." }, ...]
}
```
```

--------------------------------

### Start an autonomous web research agent job

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Initiate an autonomous research job using `firecrawl_agent` with a detailed prompt and an optional schema for structured output. The response includes a `jobId` to track progress.

```json
// Start an agent research job
{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Find the top 5 open-source LLM inference frameworks released or updated in 2024. For each, collect the GitHub URL, star count, supported model formats, and primary use case.",
    "schema": {
      "type": "object",
      "properties": {
        "frameworks": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name":           { "type": "string" },
              "githubUrl":      { "type": "string" },
              "stars":          { "type": "number" },
              "modelFormats":   { "type": "array", "items": { "type": "string" } },
              "primaryUseCase": { "type": "string" }
            },
            "required": ["name", "githubUrl"]
          }
        }
      }
    }
  }
}
// → { "jobId": "agent_7f3a9c12-..." }
```

--------------------------------

### Credit Usage Monitoring Configuration

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Set environment variables to define thresholds for credit usage warnings and critical alerts.

```bash
FIRECRAWL_CREDIT_WARNING_THRESHOLD=1000    # Emit [WARNING] log at this credit level
FIRECRAWL_CREDIT_CRITICAL_THRESHOLD=100    # Emit [ERROR] log at this credit level
```

--------------------------------

### Run Endpoint Tests

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md

Use the provided npm script to test all server endpoints. You can also specify a custom base URL and API key for testing.

```bash
# Test all endpoints
npm run test:endpoints

# Test with custom URL and API key
TEST_BASE_URL=http://localhost:8080 TEST_API_KEY=your-key npm run test:endpoints
```

--------------------------------

### Configure Firecrawl MCP Server for Claude Desktop

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Set up the Firecrawl MCP server configuration for Claude Desktop. This includes specifying the command, arguments, and environment variables like API key and retry settings.

```json
{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "fc-YOUR_API_KEY",
        "FIRECRAWL_RETRY_MAX_ATTEMPTS": "5",
        "FIRECRAWL_RETRY_INITIAL_DELAY": "2000",
        "FIRECRAWL_RETRY_MAX_DELAY": "30000",
        "FIRECRAWL_RETRY_BACKOFF_FACTOR": "3",
        "FIRECRAWL_CREDIT_WARNING_THRESHOLD": "2000",
        "FIRECRAWL_CREDIT_CRITICAL_THRESHOLD": "500"
      }
    }
  }
}
```

--------------------------------

### Windows Configuration for Cursor (v0.45.6)

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Alternative command for Windows users to configure Firecrawl MCP server in Cursor. Replace your-api-key with your actual Firecrawl API key.

```bash
cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"
```

--------------------------------

### Contributing Workflow

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Outlines the standard Git workflow for contributing to the Firecrawl MCP Server repository, including forking, branching, testing, and submitting pull requests.

```bash
1. Fork the repository
2. Create your feature branch
3. Run tests: `npm test`
4. Submit a pull request
```

--------------------------------

### firecrawl_browser_create

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Create a cloud browser session for interactive automation. This method is deprecated and `firecrawl_scrape` + `firecrawl_interact` are recommended instead.

```APIDOC
## firecrawl_browser_create (Deprecated)

### Description
Create a cloud browser session for interactive automation. Prefer `firecrawl_scrape` + `firecrawl_interact` instead.

### Parameters
#### Query Parameters
- **ttl** (integer) - Optional - Total session lifetime in seconds (30-3600).
- **activityTtl** (integer) - Optional - Idle timeout in seconds (10-3600).
- **streamWebView** (boolean) - Optional - Whether to enable live view streaming.
- **profile** (object) - Optional - Save and reuse browser state across sessions.
  - **name** (string) - Profile name (sessions with the same name share state).
  - **saveChanges** (boolean) - Whether to save changes back to the profile (default: true).

### Request Example
```json
{
  "name": "firecrawl_browser_create",
  "arguments": {
    "ttl": 600,
    "profile": { "name": "my-profile", "saveChanges": true }
  }
}
```

### Response
#### Success Response (200)
- **sessionId** (string) - The ID of the created session.
- **cdpUrl** (string) - The Chrome DevTools Protocol URL.
- **webViewUrl** (string) - The live view URL.
```

--------------------------------

### Extract structured data from multiple URLs

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Use `firecrawl_extract` to get structured data from a list of URLs. Define a schema to shape the output. Set `allowExternalLinks` and `includeSubdomains` to control link following.

```json
// Extract company information from multiple pages
{
  "name": "firecrawl_extract",
  "arguments": {
    "urls": [
      "https://openai.com/about",
      "https://anthropic.com/about",
      "https://deepmind.google/about"
    ],
    "prompt": "Extract company founding year, headquarters, number of employees, and main products",
    "schema": {
      "type": "object",
      "properties": {
        "company":      { "type": "string" },
        "founded":      { "type": "number" },
        "headquarters": { "type": "string" },
        "employees":    { "type": "string" },
        "products":     { "type": "array", "items": { "type": "string" } }
      },
      "required": ["company", "founded"]
    },
    "allowExternalLinks": false,
    "includeSubdomains": false
  }
}
// → { "data": [
//     { "company": "OpenAI",    "founded": 2015, "headquarters": "San Francisco, CA", ... },
//     { "company": "Anthropic", "founded": 2021, "headquarters": "San Francisco, CA", ... },
//     { "company": "DeepMind",  "founded": 2010, "headquarters": "London, UK", ... }
//   ] }
```

--------------------------------

### Run Firecrawl MCP Server with Self-Hosted Instance

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Configure the server to use a self-hosted Firecrawl instance by setting the FIRECRAWL_API_URL environment variable. An API key is not needed if the instance is open.

```bash
env FIRECRAWL_API_URL=https://firecrawl.your-domain.com npx -y firecrawl-mcp
```

--------------------------------

### Configure Firecrawl MCP Server in Claude Desktop

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Add this JSON configuration to your `claude_desktop_config.json` to set up the Firecrawl MCP server with custom API key, retry settings, and credit monitoring thresholds.

```json
{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE",

        "FIRECRAWL_RETRY_MAX_ATTEMPTS": "5",
        "FIRECRAWL_RETRY_INITIAL_DELAY": "2000",
        "FIRECRAWL_RETRY_MAX_DELAY": "30000",
        "FIRECRAWL_RETRY_BACKOFF_FACTOR": "3",

        "FIRECRAWL_CREDIT_WARNING_THRESHOLD": "2000",
        "FIRECRAWL_CREDIT_CRITICAL_THRESHOLD": "500"
      }
    }
  }
}
```

--------------------------------

### Testing Cloud Endpoints with Custom Base URL

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Run endpoint tests for the cloud service, specifying a custom base URL and API key.

```bash
# Test endpoints with custom base URL
TEST_BASE_URL=http://localhost:3000 TEST_API_KEY=fc-YOUR_API_KEY npm run test:endpoints
```

--------------------------------

### Configure Firecrawl MCP Server in Cursor (v0.48.6+)

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

JSON configuration for adding Firecrawl MCP server to Cursor. Replace YOUR-API-KEY with your actual Firecrawl API key.

```json
{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR-API-KEY"
      }
    }
  }
}
```

--------------------------------

### Click a specific element by ref using bash commands

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Interacts with a scraped page by typing into an element and then clicking another element, identified by their references. This is an alternative to natural language interaction.

```json
{
  "name": "firecrawl_interact",
  "arguments": {
    "scrapeId": "scrape_a1b2c3",
    "code": "agent-browser type @e12 'firecrawl documentation' && agent-browser click @e15",
    "language": "bash"
  }
}
```

--------------------------------

### Configure Firecrawl MCP Server for Cursor / Windsurf

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Configure the Firecrawl MCP server for use with Cursor or Windsurf. This involves setting the command, arguments, and the FIRECRAWL_API_KEY environment variable.

```json
{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": { "FIRECRAWL_API_KEY": "YOUR_API_KEY" }
    }
  }
}
```

--------------------------------

### Run agent with focused URLs

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

For faster research on known domains, provide a list of specific URLs to the `firecrawl_agent`. This focuses the agent's efforts on the most relevant pages.

```json
// Agent with focused URLs (faster for known domains)
{
  "name": "firecrawl_agent",
  "arguments": {
    "urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    "prompt": "Compare all available API plans: list the plan names, monthly price, rate limits (requests/minute), and any usage caps."
  }
}
```

--------------------------------

### V1 Endpoints (Legacy)

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md

These endpoints are part of the legacy V1 API and are available when CLOUD_SERVICE is set to true.

```APIDOC
## SSE

### Description
Provides Server-Sent Events for the legacy V1 API.

### Method
GET

### Endpoint
`/:apiKey/sse`

## Messages

### Description
Handles message-based communication for the legacy V1 API.

### Method
GET

### Endpoint
`/:apiKey/messages`
```

--------------------------------

### Default Server Configuration

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Defines default retry behavior and credit usage thresholds for the server. These values can be overridden by environment variables.

```typescript
const CONFIG = {
  retry: {
    maxAttempts: 3, // Number of retry attempts for rate-limited requests
    initialDelay: 1000, // Initial delay before first retry (in milliseconds)
    maxDelay: 10000, // Maximum delay between retries (in milliseconds)
    backoffFactor: 2, // Multiplier for exponential backoff
  },
  credit: {
    warningThreshold: 1000, // Warn when credit usage reaches this level
    criticalThreshold: 100, // Critical alert when credit usage reaches this level
  },
};
```

--------------------------------

### Run Firecrawl MCP Server with Streamable HTTP Local Mode

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Runs the Firecrawl MCP server using Streamable HTTP transport locally. Requires setting FIRECRAWL_API_KEY and HTTP_STREAMABLE_SERVER environment variables.

```bash
env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp
```

--------------------------------

### Configuration Environment Variables

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Environment variables for configuring Firecrawl credit usage monitoring and retry mechanisms.

```APIDOC
# Credit Usage Monitoring

- `FIRECRAWL_CREDIT_WARNING_THRESHOLD`: (Integer) Emit [WARNING] log at this credit level.
- `FIRECRAWL_CREDIT_CRITICAL_THRESHOLD`: (Integer) Emit [ERROR] log at this credit level.

# Retry Configuration

- `FIRECRAWL_RETRY_MAX_ATTEMPTS`: (Integer) Maximum number of retry attempts.
- `FIRECRAWL_RETRY_INITIAL_DELAY`: (Integer) Initial delay in milliseconds for retries.
- `FIRECRAWL_RETRY_MAX_DELAY`: (Integer) Maximum delay in milliseconds for retries.
- `FIRECRAWL_RETRY_BACKOFF_FACTOR`: (Integer) Backoff factor for retry delays.
```

--------------------------------

### Configure Firecrawl Cloud API with Custom Retries

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Set environment variables to configure the Firecrawl cloud API with custom retry attempts, delays, and backoff factors. Ensure FIRECRAWL_API_KEY is set for cloud usage.

```bash
# Required for cloud API
export FIRECRAWL_API_KEY=your-api-key

# Optional retry configuration
export FIRECRAWL_RETRY_MAX_ATTEMPTS=5        # Increase max retry attempts
export FIRECRAWL_RETRY_INITIAL_DELAY=2000    # Start with 2s delay
export FIRECRAWL_RETRY_MAX_DELAY=30000       # Maximum 30s delay
export FIRECRAWL_RETRY_BACKOFF_FACTOR=3      # More aggressive backoff

# Optional credit monitoring
export FIRECRAWL_CREDIT_WARNING_THRESHOLD=2000    # Warning at 2000 credits
export FIRECRAWL_CREDIT_CRITICAL_THRESHOLD=500    # Critical at 500 credits
```

--------------------------------

### Interact with a scraped page using a natural language prompt

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Performs actions on a previously scraped page using a natural language prompt. Requires a scrapeId from a prior scrape operation.

```json
{
  "name": "firecrawl_interact",
  "arguments": {
    "scrapeId": "scrape_a1b2c3",
    "prompt": "Type 'firecrawl documentation' into the search box and click the first result, then return the page title and URL."
  }
}
```

--------------------------------

### Configure Firecrawl MCP Server in Windsurf

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

JSON configuration to add Firecrawl MCP server to Windsurf. Replace YOUR_API_KEY with your actual Firecrawl API key.

```json
{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

--------------------------------

### Interact with a scraped page using explicit bash commands

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Executes explicit bash commands within a live browser session for a scraped page. Supports agent-browser commands and allows for a custom timeout.

```json
{
  "name": "firecrawl_interact",
  "arguments": {
    "scrapeId": "scrape_a1b2c3",
    "code": "agent-browser snapshot -i -c",
    "language": "bash",
    "timeout": 15
  }
}
```

--------------------------------

### Configure Firecrawl Self-Hosted Instance

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Set environment variables for a self-hosted Firecrawl instance, including the custom API URL and optional API key for authentication. Custom retry configurations can also be applied.

```bash
# Required for self-hosted
export FIRECRAWL_API_URL=https://firecrawl.your-domain.com

# Optional authentication for self-hosted
export FIRECRAWL_API_KEY=your-api-key  # If your instance requires auth

# Custom retry configuration
export FIRECRAWL_RETRY_MAX_ATTEMPTS=10
export FIRECRAWL_RETRY_INITIAL_DELAY=500     # Start with faster retries
```

--------------------------------

### Use Firecrawl Search Tool

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Use this tool to search the web and optionally extract content from search results. It's best for finding specific information across multiple websites when the source is unknown. Ensure the 'query' argument is provided.

```json
{
  "name": "firecrawl_search",
  "arguments": {
    "query": "latest AI research papers 2023",
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}
```

--------------------------------

### Environment Variables for Firecrawl Server Configuration

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Lists essential environment variables for configuring the Firecrawl server, including API authentication, transport modes, server settings, and retry logic.

```bash
# ── Required (choose one) ──────────────────────────────────────────────
FIRECRAWL_API_KEY=fc-YOUR_API_KEY          # Cloud API authentication
FIRECRAWL_API_URL=https://fc.your-co.com  # Self-hosted instance URL

# ── Transport mode (mutually exclusive; default is stdio) ──────────────
CLOUD_SERVICE=true                         # Versioned cloud endpoints (/:apiKey/v2/sse)
SSE_LOCAL=true                             # SSE on localhost
HTTP_STREAMABLE_SERVER=true                # Streamable HTTP on localhost:PORT/mcp

# ── Server ─────────────────────────────────────────────────────────────
PORT=3000                                  # HTTP listen port (default: 3000)
HOST=localhost                             # Bind address (default: localhost; 0.0.0.0 in cloud mode)

# ── Retry configuration ────────────────────────────────────────────────
FIRECRAWL_RETRY_MAX_ATTEMPTS=3             # Max retry attempts on rate-limit errors
FIRECRAWL_RETRY_INITIAL_DELAY=1000         # First retry delay in ms
FIRECRAWL_RETRY_MAX_DELAY=10000            # Maximum delay between retries in ms
FIRECRAWL_RETRY_BACKOFF_FACTOR=2           # Exponential backoff multiplier
```

--------------------------------

### Update Endpoint URLs from V1 to V2

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md

When migrating from V1 to V2, update your endpoint URLs. V1 endpoints like '/:apiKey/sse' and '/:apiKey/messages' should be changed to '/:apiKey/v2/sse' and '/:apiKey/v2/messages' respectively.

```bash
Old: /:apiKey/sse
New: /:apiKey/v2/sse

Old: /:apiKey/messages
New: /:apiKey/v2/messages
```

--------------------------------

### V2 Endpoints (Current)

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md

These endpoints represent the current V2 API, offering modern features and improvements. They are available when CLOUD_SERVICE is set to true.

```APIDOC
## SSE (V2)

### Description
Provides Server-Sent Events using the modern V2 API.

### Method
GET

### Endpoint
`/:apiKey/v2/sse`

## Messages (V2)

### Description
Handles message-based communication with the modern V2 API.

### Method
GET

### Endpoint
`/:apiKey/v2/messages`
```

--------------------------------

### Perform Web, Image, and News Searches with firecrawl_search

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Executes web searches and optionally scrapes content from results. Supports advanced search modifiers and domain filtering. Use the `sources` parameter to specify 'web', 'image', or 'news'. Inline scraping is supported but should be used sparingly.

```json
{
  "name": "firecrawl_search",
  "arguments": {
    "query": "firecrawl MCP server configuration 2024",
    "limit": 5,
    "sources": [{ "type": "web" }]
  }
}
```

```json
{
  "name": "firecrawl_search",
  "arguments": {
    "query": "rate limiting best practices",
    "limit": 5,
    "includeDomains": ["engineering.example.com", "blog.stripe.com"]
  }
}
```

```json
{
  "name": "firecrawl_search",
  "arguments": {
    "query": "OpenAI GPT-5 announcement",
    "limit": 8,
    "sources": [{ "type": "news" }],
    "lang": "en",
    "country": "us"
  }
}
```

```json
{
  "name": "firecrawl_search",
  "arguments": {
    "query": "site:docs.firecrawl.dev extract structured data",
    "limit": 3,
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}
```

```json
{
  "name": "firecrawl_search",
  "arguments": {
    "query": "web scraping API pricing",
    "excludeDomains": ["competitor1.com", "competitor2.io"],
    "limit": 10
  }
}
```

--------------------------------

### Scrape Single URL for Screenshot with Actions

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Captures a screenshot of a URL after performing a series of actions like typing into fields, clicking buttons, and waiting. Useful for dynamic pages or login forms. Specify actions in sequence.

```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/login",
    "formats": ["screenshot"],
    "actions": [
      { "type": "write",      "selector": "#email",    "text": "user@example.com" },
      { "type": "write",      "selector": "#password", "text": "secret" },
      { "type": "click",      "selector": "button[type=submit]" },
      { "type": "wait",       "milliseconds": 2000 },
      { "type": "screenshot"  }
    ],
    "screenshotOptions": { "fullPage": true }
  }
}
```

--------------------------------

### Cloud Service Versioned Endpoints

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

The server exposes V1 (legacy) and V2 (current) endpoints when CLOUD_SERVICE is true. Both require the API key in the URL path.

```APIDOC
## Cloud Service Endpoints

### V2 Endpoints (Current)

- **Method**: GET
- **Endpoint**: `/:apiKey/v2/sse`
- **Description**: SSE connection.

- **Method**: POST
- **Endpoint**: `/:apiKey/v2/messages`
- **Description**: Send MCP messages.

### V1 Endpoints (Legacy)

- **Method**: GET
- **Endpoint**: `/:apiKey/sse`
- **Description**: SSE connection.

- **Method**: POST
- **Endpoint**: `/:apiKey/messages`
- **Description**: Send MCP messages.

### Health Check

- **Method**: GET
- **Endpoint**: `/health`
- **Description**: Health check endpoint. Returns 'ok' with a 200 status code. No authentication required.
```

--------------------------------

### Scrape Single URL for Branding Information

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Use the 'branding' format to extract comprehensive brand identity elements like colors, fonts, typography, spacing, logos, and UI components for design analysis.

```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["branding"]
  }
}
```

--------------------------------

### Cloud Service Versioned Endpoints

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Overview of V1 (legacy) and V2 (current) API endpoints for the cloud service, including SSE and message endpoints. API key is required in the URL path.

```http
# V2 endpoints (current — use these for new integrations)
GET  /:apiKey/v2/sse       → SSE connection
POST /:apiKey/v2/messages  → Send MCP messages

# V1 endpoints (legacy — maintained for backward compatibility)
GET  /:apiKey/sse          → SSE connection
POST /:apiKey/messages     → Send MCP messages

# Health check (no auth required)
GET  /health               → 200 OK, body: "ok"
```

--------------------------------

### Configure Firecrawl MCP Server in Cursor (v0.45.6)

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Command to configure Firecrawl MCP server in older versions of Cursor. Replace your-api-key with your actual Firecrawl API key.

```bash
env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp
```

--------------------------------

### Scrape Single URL for Markdown Content

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Fetches a single URL and returns its main content formatted as Markdown. Useful for extracting article text. Requires specifying the URL and desired format.

```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/blog/ai-trends-2024",
    "formats": ["markdown"],
    "onlyMainContent": true,
    "waitFor": 3000
  }
}
```

--------------------------------

### Create Browser Session

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Deprecated: Prefer `firecrawl_scrape` + `firecrawl_interact`. Creates a cloud browser session for interactive automation. Supports optional session lifetime and idle timeout.

```json
{
  "name": "firecrawl_browser_create",
  "arguments": {
    "ttl": 600,
    "profile": { "name": "my-profile", "saveChanges": true }
  }
}
```

--------------------------------

### Parse local PDF file to markdown

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Extracts content from a local PDF file and converts it to markdown format. Supports options like limiting the number of pages and focusing on main content.

```json
{
  "name": "firecrawl_parse",
  "arguments": {
    "filePath": "/home/user/reports/annual-report-2024.pdf",
    "formats": ["markdown"],
    "parsers": ["pdf"],
    "pdfOptions": { "maxPages": 20 },
    "onlyMainContent": true
  }
}
```

--------------------------------

### Scrape Single URL for Branding Information

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Extracts branding elements such as primary color, font family, and logo URL from a given URL. Useful for brand analysis or consistency checks.

```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://stripe.com",
    "formats": ["branding"]
  }
}
```

--------------------------------

### firecrawl_scrape

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Fetches a URL and returns its content in one or more formats. Supports various options like output formats, content extraction, actions, proxy selection, and caching.

```APIDOC
## `firecrawl_scrape` — Scrape a Single URL

Fetches a URL and returns its content in one or more formats: `markdown`, `html`, `rawHtml`, `links`, `screenshot`, `json` (LLM-extracted), `query` (targeted Q&A), `summary`, `branding`, `audio`, or `changeTracking`. JSON format with a schema is the recommended choice whenever you need specific data fields rather than full page content. Supports actions (click, type, scroll, wait), proxy selection, geo-location, browser profiles, caching (`maxAge`), and lockdown mode for air-gapped compliance.

### Request Example (Markdown Output)
```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/blog/ai-trends-2024",
    "formats": ["markdown"],
    "onlyMainContent": true,
    "waitFor": 3000
  }
}
```

### Response Example (Markdown Output)
```json
{
  "markdown": "# AI Trends 2024\n\nThe landscape of artificial intelligence..."
}
```

### Request Example (JSON Output with Schema)
```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://shop.example.com/product/42",
    "formats": ["json"],
    "jsonOptions": {
      "prompt": "Extract product details",
      "schema": {
        "type": "object",
        "properties": {
          "name":        { "type": "string" },
          "price":       { "type": "number" },
          "currency":    { "type": "string" },
          "inStock":     { "type": "boolean" },
          "description": { "type": "string" },
          "images":      { "type": "array", "items": { "type": "string" } }
        },
        "required": ["name", "price"]
      }
    }
  }
}
```

### Response Example (JSON Output)
```json
{
  "json": {
    "name": "Widget Pro",
    "price": 49.99,
    "currency": "USD",
    "inStock": true,
    "images": ["https://..."]
  }
}
```

### Request Example (Screenshot with Actions)
```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/login",
    "formats": ["screenshot"],
    "actions": [
      { "type": "write",      "selector": "#email",    "text": "user@example.com" },
      { "type": "write",      "selector": "#password", "text": "secret" },
      { "type": "click",      "selector": "button[type=submit]" },
      { "type": "wait",       "milliseconds": 2000 },
      { "type": "screenshot"  }
    ],
    "screenshotOptions": { "fullPage": true }
  }
}
```

### Request Example (Branding Extraction)
```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://stripe.com",
    "formats": ["branding"]
  }
}
```

### Response Example (Branding Extraction)
```json
{
  "branding": {
    "primaryColor": "#635BFF",
    "fontFamily": "Sohne",
    "logoUrl": "..."
  }
}
```

### Request Example (Cached Scrape)
```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://docs.example.com/api",
    "formats": ["markdown"],
    "maxAge": 172800000
  }
}
```

### Request Example (Stealth Proxy + Geo-location)
```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://geo-restricted.example.com",
    "formats": ["markdown"],
    "proxy": "stealth",
    "location": { "country": "US", "languages": ["en-US"] }
  }
}
```
```

--------------------------------

### Scrape Single URL with Markdown

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

Use markdown format when the entire page content is genuinely required, such as for summarizing an article or analyzing page structure. Set `onlyMainContent` to true to focus on the primary content.

```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/article",
    "formats": ["markdown"],
    "onlyMainContent": true
  }
}
```

--------------------------------

### Scrape Single URL with Caching

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Fetches content from a URL and caches the result for a specified duration (in milliseconds) to speed up subsequent requests. Use `maxAge` to control cache validity.

```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://docs.example.com/api",
    "formats": ["markdown"],
    "maxAge": 172800000
  }
}
```

--------------------------------

### Crawl an Entire Site with firecrawl_crawl

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Initiates an asynchronous crawl job for an entire site, extracting content from all reachable pages. Use path filters and depth limits to manage response size. Webhook notifications can be configured for completion.

```json
{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://docs.example.com/guides",
    "maxDiscoveryDepth": 3,
    "limit": 50,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true,
    "sitemap": "include",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}
```

```json
{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://example.com",
    "includePaths": ["/blog/*", "/docs/*"],
    "excludePaths": ["/blog/tags/*", "/docs/legacy/*"],
    "maxDiscoveryDepth": 2,
    "limit": 30,
    "prompt": "Focus on pages with code examples and API documentation"
  }
}
```

```json
{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://example.com/products",
    "limit": 100,
    "webhook": "https://my-app.example.com/webhooks/crawl-done",
    "webhookHeaders": {
      "Authorization": "Bearer webhook-secret-token"
    }
  }
}
```

--------------------------------

### Focus Agent Research with Specific URLs

Source: https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md

When you have a set of relevant URLs, you can provide them to `firecrawl_agent` to focus its research. This is useful for comparing information or gathering data from specific sources.

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

--------------------------------

### firecrawl_map

Source: https://context7.com/firecrawl/firecrawl-mcp-server/llms.txt

Discover all URLs on a website. Optionally filter results with a `search` keyword or include sitemaps for more comprehensive discovery.

```APIDOC
## `firecrawl_map` — Discover All URLs on a Site

Maps a website to enumerate all indexed URLs. Optionally filter results with a `search` keyword to find specific pages quickly — use this before `firecrawl_scrape` when you don't know the exact URL of the content you need.

### Parameters

#### Arguments

- **url** (string) - Required - The starting URL to map.
- **search** (string) - Optional - A keyword to filter discovered URLs.
- **limit** (integer) - Optional - The maximum number of URLs to return.
- **includeSubdomains** (boolean) - Optional - Whether to include URLs from subdomains.
- **sitemap** (string) - Optional - Whether to include sitemap URLs ('include' or 'exclude').
- **ignoreQueryParameters** (boolean) - Optional - Whether to ignore query parameters when discovering URLs.

### Request Example

```json
{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://docs.example.com",
    "limit": 200,
    "includeSubdomains": false
  }
}
```

### Response Example

```json
{
  "urls": ["https://docs.example.com/", "https://docs.example.com/quickstart", "https://docs.example.com/api/scrape", ...]
}
```
```