Firecrawl

src="https://raw.githubusercontent.com/firecrawl/firecrawl-mcp-server/main/img/fire.png" height="140"

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
• Search an index built for coding agents: GitHub issues, merged pull requests, READMEs, and docs
• Scrape any URL into clean, structured data
• Interact with pages — click, navigate, and operate
• Deep research with autonomous agent
• Check current and historical Firecrawl credit usage
• 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.

When to Use This Server

• Use firecrawl_scrape when you have a known URL and want its content as markdown or as JSON matching a schema you supply.
• Use firecrawl_map when you need to discover URLs on a site without fetching their content.
• Use firecrawl_crawl when you need content from many pages under a site; set limit, includePaths/excludePaths, or maxDiscoveryDepth to bound it.
• Use firecrawl_search when you're starting from a query rather than a URL and want ranked web results; add scrapeOptions if you also want page content fetched in the same call (the search-only endpoint never fetches content).
• Use firecrawl_interact when a page needs a click, type, or navigate action before you can read it — pass a url for a fresh page or a scrapeId to continue on one you already scraped.
• Use the firecrawl_monitor_* tools when the same page needs to be checked on a recurring schedule with diffs and change alerts, rather than fetched once.
• Use firecrawl_credit_usage to check credits left or monthly consumption, optionally broken down by API key.
• Consider something else when you need to hold a browser session open across many of your own steps with your own retry and termination logic: each firecrawl_interact call runs one prompt or code turn to completion and returns control — the session can persist across calls via scrapeId and ends with firecrawl_interact_stop, but you cannot drive it interactively step-by-step from the client side within a single call.

This server lists 27 tools when the full profile registers with default settings (feedback tools included, not running in local-keyless mode). Setting FIRECRAWL_NO_SEARCH_FEEDBACK=1 and/or FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 removes the corresponding feedback tools and reduces this count, as does local keyless startup. For clients with a tool-slot limit: the hosted keyless endpoint (https://mcp.firecrawl.dev/v2/mcp, no API key) exposes only 3 — firecrawl_scrape, firecrawl_search, firecrawl_parse — and the dedicated search-only endpoint (https://mcp.firecrawl.dev/v2/mcp-search) exposes a fixed set of 9 tools (search, developer, government, and research search, plus Alexandria catalogue lookup and execution).

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 parse work without an API key (rate-limited). Other tools such as crawl, map, and agent still need a key.

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

For an interactive account connection, configure your MCP client to use this server URL. This is an MCP endpoint, not a browser page; use the client's account-connection flow and do not add a second Firecrawl server entry when reconnecting:

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

For an API-key connection (for example, an unattended integration), keep the server URL as:

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

Then configure the client's secure header or secret setting with:

Authorization: Bearer <FIRECRAWL_API_KEY>

Never put an API key in the server URL. Never put an API key in an agent chat. Configure it directly in the client or secret manager. See the hosted MCP setup guide and the agent onboarding guide for client-specific instructions.

Search-only endpoint

A fixed-scope search surface is also hosted at:

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

It exposes a fixed set of nine tools: firecrawl_search, firecrawl_developer_search, firecrawl_gov_search, the four firecrawl_research_* tools, and the two Alexandria tools firecrawl_find_tools and firecrawl_scrape. Its firecrawl_search fetches no page content, and the surface has its own OAuth identity; the full endpoint above is unchanged. It backs a published connector listing, so its tool set is a contract rather than a profile to tune. See docs/search-profile.md for the full contract and what a change to it involves.

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:

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

Running with Docker

The ghcr.io/firecrawl/firecrawl-mcp-server image runs the same server as npx -y firecrawl-mcp. Every build from main is tagged latest, v<package version> and sha-<commit sha>. v<package version> moves to the newest build of that version, so pin sha-<commit sha> (or a digest) when you need a fixed image.

stdio (the default), for MCP clients that launch the server as a command:

docker run -i --rm -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY ghcr.io/firecrawl/firecrawl-mcp-server:latest

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "FIRECRAWL_API_KEY", "ghcr.io/firecrawl/firecrawl-mcp-server:latest"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Streamable HTTP, served at http://localhost:3000/mcp:

docker run --rm -p 127.0.0.1:3000:3000 \
  -e HTTP_STREAMABLE_SERVER=true \
  -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  ghcr.io/firecrawl/firecrawl-mcp-server:latest

The image sets HOST=0.0.0.0 and PORT=3000; override PORT (and the -p mapping) to listen elsewhere. The server uses the container's FIRECRAWL_API_KEY for requests that don't send their own credential, so the example publishes the port on 127.0.0.1 only; don't expose it more widely unless clients must supply their own key. Set FIRECRAWL_API_URL to use a self-hosted Firecrawl API. The container runs as the unprivileged node user.

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

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 <fco_access_token> 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.

Hardened HTTP preset (CLOUD_SERVICE=true)

CLOUD_SERVICE=true serves the tools over streamable HTTP on PORT (default 3000), bound to 0.0.0.0, with stricter defaults for a shared deployment:

• every request must carry a credential (an API key or an OAuth access token);
• safe mode: scrape is read-only (see the scrape tool below);
• firecrawl_parse accepts uploads only and never reads local files.

FASTMCP_ENDPOINT selects the surface: /v2/mcp (default) serves the full tool set, /v2/mcp-oauth the account surface, and /v2/mcp-search (which also requires FIRECRAWL_MCP_SEARCH_OAUTH_ONLY=true) the search-only surface described below.

Search-only surface (hosted)

In hosted mode (CLOUD_SERVICE=true) a second in-process instance serves the search-only endpoint on local port 3001. The hosted deployment's reverse proxy routes /v2/mcp-search to that port, and the OAuth protected-resource identifier is https://mcp.firecrawl.dev/v2/mcp-search.

FIRECRAWL_MCP_SEARCH_ENABLED (default true) is the supported operational toggle; set it to false to prevent the search instance from starting. The Node process also accepts FIRECRAWL_MCP_SEARCH_PORT, FIRECRAWL_MCP_SEARCH_ENDPOINT, and FIRECRAWL_MCP_SEARCH_RESOURCE_URL for isolated tests. Those overrides do not reconfigure the deployment's proxy routes or the authorization server allowlist and must not be used independently in the hosted deployment.

The search instance requires authentication for every request (including tools/list) and rejects OAuth tokens whose audience does not match its own resource.

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 have a programming question (a library, an API contract, an error message, a known bug): use developer search
• If you have a legal or regulatory question (a statute, regulation, code, court opinion, or other US government publication): use the Firecrawl Government Index
• If you need scientific papers (biomedical, life-science, clinical, or arXiv literature): use research tools — they search paper abstracts and full text. search with categories: ["research"] is a different thing: a website filter over ordinary web results.
• If you need multi-source research that returns structured data, do not know the URLs, or the answer spans several sites (an entity plus its fields, a list, a dataset): 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
• If you need data from a catalogued provider (Alexandria): search with sources: ["alexandria"], inspect the selected contract with find_tools, and execute it with scrape alexandria

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
search	Web search for info	results[]
find_tools	Alexandria catalogue browsing and URL lookup	providers, tool contracts and nextTool navigation
developer	Programming questions over developer sources	results[] with passages
gov	US primary law and regulatory material	results[] with snippets
agent	Multi-source research, unknown or many sites	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. Hardened HTTP preset and the hosted server: With CLOUD_SERVICE=true, as on the hosted server, scrape is read-only. It takes no browser actions and cannot accept provider terms. A named profile loads saved browser state without saving changes to it, and the full endpoint's firecrawl_search treats scrapeOptions.profile the same way. To save browser state to a profile, open the page with firecrawl_interact (see below). An organization admin accepts terms in the dashboard.

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": "remote work stipend policies at tech companies",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true,
      "redactPII": true
    }
  }
}

Set highlights to true to request query-relevant highlights or false to keep the original search snippets. Omit it to use the API's default behavior.