Firecrawl Mcp Server

Firecrawl MCP Server

A Model Context Protocol (MCP) server that brings Firecrawl to MCP-compatible AI agents — search, scrape, and interact with the live web for clean, agent-ready context.

> Big thanks to @vrknetha, @knacklabs for the initial implementation!

Features

• Search the web and get full page content
• Scrape any URL into clean, structured data
• Interact with pages — click, navigate, and operate
• Deep research with autonomous agent
• Automatic retries and rate limiting
• Cloud and self-hosted support
• SSE support

> Play around with our MCP Server on MCP.so's playground or on Klavis AI.

Installation

Hosted MCP (keyless free tier)

Connect to the remote hosted server with no setup:

https://mcp.firecrawl.dev/v2/mcp

On the keyless free tier, scrape, search, and interact work without an API key (rate-limited). Other tools such as crawl, map, agent, and extract still need a key.

Prefer an API key or OAuth whenever the human can sign up. It unlocks the full tool set and higher limits. With a key, use:

https://mcp.firecrawl.dev/{FIRECRAWL_API_KEY}/v2/mcp

See the MCP server docs and the agent onboarding guide for setup details.

Running with npx

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

Manual Installation

npm install -g firecrawl-mcp

Running on Cursor

Configuring Cursor 🖥️ Note: Requires Cursor version 0.45.6+ For the most up-to-date configuration instructions, please refer to the official Cursor documentation on configuring MCP servers: Cursor MCP Server Configuration Guide

To configure Firecrawl MCP in Cursor v0.48.6

1. Open Cursor Settings
2. Go to Features > MCP Servers
3. Click "+ Add new global MCP server"
4. Enter the following code:

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

To configure Firecrawl MCP in Cursor v0.45.6

1. Open Cursor Settings
2. Go to Features > MCP Servers
3. Click "+ Add New MCP Server"
4. Enter the following:

• Name: "firecrawl-mcp" (or your preferred name)
• Type: "command"
• Command: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

> If you are using Windows and are running into issues, try cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"

Replace your-api-key with your Firecrawl API key. If you don't have one yet, you can create an account and get it from https://www.firecrawl.dev/app/api-keys

After adding, refresh the MCP server list to see the new tools. The Composer Agent will automatically use Firecrawl MCP when appropriate, but you can explicitly request it by describing your web scraping needs. Access the Composer via Command+L (Mac), select "Agent" next to the submit button, and enter your query.

Running on Windsurf

Add this to your ./codeium/windsurf/model_config.json:

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

Running with Streamable HTTP Local Mode

To run the server using Streamable HTTP locally instead of the default stdio transport:

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

Use the url: http://localhost:3000/mcp

Installing via Smithery (Legacy)

To install Firecrawl for Claude Desktop automatically via Smithery:

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

Running on VS Code

For one-click installation, click one of the install buttons below...

[](https://insiders.vscode.dev/redirect/mcp/install?name=firecrawl&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Firecrawl%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22firecrawl-mcp%22%5D%2C%22env%22%3A%7B%22FIRECRAWLAPIKEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=firecrawl&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Firecrawl%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22firecrawl-mcp%22%5D%2C%22env%22%3A%7B%22FIRECRAWLAPIKEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D&quality=insiders)

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (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}"
        }
      }
    }
  }
}

Optionally, you can add it to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others:

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

Configuration

Environment Variables

Required for Cloud API

• FIRECRAWL_API_KEY: Your Firecrawl API key
• Required when using cloud API (default)
• Optional when using self-hosted instance with FIRECRAWL_API_URL
• FIRECRAWL_API_URL (Optional): Custom API endpoint for self-hosted instances
• Example: https://firecrawl.your-domain.com
• If not provided, the cloud API will be used (requires API key)

MCP OAuth (Bearer access tokens)

Hosted Firecrawl can issue OAuth access tokens (fco_…) via the authorization server on firecrawl.dev. This MCP server forwards whichever credential it resolves to the Firecrawl API as Authorization: Bearer ….

• HTTP stream transports (CLOUD_SERVICE=true, HTTP_STREAMABLE_SERVER=true, or SSE_LOCAL=true): Clients should send Authorization: Bearer on MCP requests. An OAuth bearer token takes precedence over x-firecrawl-api-key / x-api-key when both are present.
• stdio: Use FIRECRAWL_OAUTH_TOKEN for a static access token, or keep using FIRECRAWL_API_KEY for an API key.

Use access tokens (fco_…) only. Refresh tokens (fcr_…) must be exchanged at the token endpoint, not passed to the scrape/search API.

Configuration Examples

For cloud API usage:

export FIRECRAWL_API_KEY=your-api-key

For self-hosted instance:

# 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

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

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

How to Choose a Tool

Use this guide to select the right tool for your task:

• If you know the exact URL you want: use scrape (with JSON format for structured data)
• If you have multiple known URLs: call scrape for each URL. If you specifically need one bulk API operation, use the Firecrawl API batch endpoint outside MCP.
• If you need to discover URLs on a site: use map
• If you want to search the web for info: use search
• If you need complex research across multiple unknown sources: use agent
• If you want to analyze a whole site or section: use crawl (with limits!)
• If you need interactive browser automation (click, type, navigate): use interact with a URL for a fresh page, or scrape + interact when you already scraped the page or need tighter scrape control

Quick Reference Table

| Tool | Best for | Returns | | ------------ | ---------------------------------------------- | ------------------------------ | | scrape | Single page content | JSON (preferred) or markdown | | interact | Interact with a URL or scraped page | Execution result + scrapeId for URL mode | | map | Discovering URLs on a site | URL[] | | crawl | Multi-page extraction (with limits) | final crawl status/data after internal polling | | parse | Files and hosted upload refs | markdown, JSON, or document output | | extract | Structured extraction from URLs | JSON structured data | | search | Web search for info | results[] | | agent | Complex multi-source research | JSON (structured data) | | monitor | Recurring page checks | monitor/check metadata and diffs | | research | Paper and GitHub repository research | research results and repo matches |

Format Selection Guide

When using scrape, choose the right format:

• JSON format (recommended for most cases): Use when you need specific data from a page. Define a schema based on what you need to extract. This keeps responses small and avoids context window overflow.
• Markdown format (use sparingly): Only when you genuinely need the full page content, such as reading an entire article for summarization or analyzing page structure.

Available Tools

1. Scrape Tool (firecrawl_scrape)

Scrape content from a single URL with advanced options.

Best for:

• Single page content extraction, when you know exactly which page contains the information.

Not recommended for:

• Extracting content from multiple pages (use repeated scrape calls for known URLs, or map + scrape to discover URLs first, or crawl for full page content)
• When you're unsure which page contains the information (use search)

Common mistakes:

• Passing a list of URLs to one scrape call. Call scrape once per URL in MCP. If you specifically need one bulk API operation, use the Firecrawl API batch endpoint outside MCP.
• Using markdown format by default (use JSON format to extract only what you need).

Choosing the right format:

• JSON format (preferred): For most use cases, use JSON format with a schema to extract only the specific data needed. This keeps responses focused and prevents context window overflow.
• Markdown format: Only when the task genuinely requires full page content (e.g., summarizing an entire article, analyzing page structure).

Prompt Example:

> "Get the product details from https://example.com/product."

Usage Example (JSON format - preferred):

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/product",
    "formats": [
      {
        "type": "json",
        "prompt": "Extract the product information",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "price": { "type": "number" },
            "description": { "type": "string" }
          },
          "required": ["name", "price"]
        }
      }
    ]
  }
}

Usage Example (markdown format - when full content needed):

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

Usage Example (branding format - extract brand identity):

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

Branding format: Extracts comprehensive brand identity (colors, fonts, typography, spacing, logo, UI components) for design analysis or style replication. Privacy: Set redactPII: true to return content with personally identifiable information redacted.

Returns:

• JSON structured data, markdown, branding profile, or other formats as specified.

2. Map Tool (firecrawl_map)

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

Best for:

• Discovering URLs on a website before deciding what to scrape
• Finding specific sections of a website

Not recommended for:

• When you already know which specific URL you need (use scrape)
• When you need the content of the pages (use scrape after mapping)

Common mistakes:

• Using crawl to discover URLs instead of map

Prompt Example:

> "List all URLs on example.com."

Usage Example:

{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com"
  }
}

Returns:

• Array of URLs found on the site

3. Search Tool (firecrawl_search)

Search the web and optionally extract content from search results.

Best for:

• Finding specific information across multiple websites, when you don't know which website has the information.
• When you need the most relevant content for a query

Not recommended for:

• When you already know which website to scrape (use scrape)
• When you need comprehensive coverage of a single website (use map or crawl)

Common mistakes:

• Using crawl or map for open-ended questions (use search instead)

Usage Example:

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

Returns:

• Array of search results (with optional scraped content), plus an id field. Pass that id to firecrawl_search_feedback after you've used the results to refund 1 credit (search costs 2) and improve search quality.

Prompt Example:

> "Find the latest research papers on AI published in 2023."

3b. Search Feedback Tool (firecrawl_search_feedback)

Sends structured feedback on a previous firecrawl_search result. The first feedback per search id refunds 1 credit and improves Firecrawl's search quality. Idempotent per search id.

Call this after every search you actually use (or that didn't help). Bad/partial feedback with missingContent is just as valuable as good feedback.

Opt out: set FIRECRAWL_NO_SEARCH_FEEDBACK=1 (or FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1) in the environment when starting the MCP server. The firecrawl_search_feedback tool will not be registered, so agents can't call it. Team admins can also disable feedback server-side; in that case the tool is registered but always returns feedbackErrorCode: "TEAM_OPTED_OUT".

Most important field: missingContent. It's an array of specific pieces of content the agent expected to find but did not. One entry per missing topic — these aggregate across teams and tell us what to index next.

Daily refund cap (per team, per UTC day, default 100 credits). Once a team's `creditsRefundedTo

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: firecrawl
• Source: firecrawl/firecrawl-mcp-server
• License: MIT
• Homepage: https://firecrawl.dev

Install and usage instructions live in the source repository linked above.