MCP Connector

Scrape and Extract Web Data

MCP server bringing Firecrawl's web search, scraping, crawling, and browser interaction to AI agents as clean markdown or schema-validated JSON.


84
Spark score
out of 100
Updated 2 days ago
Source checked Nov 19, 2026
Version 3.36.1
Models
universal

Add to Favorites

Why it matters

Automate web data extraction for AI assistants. This asset scrapes single pages, crawls entire sites, and extracts structured data, making web content readily available for AI processing.

Outcomes

What it gets done

01

Scrape content from single web pages.

02

Perform batch scraping of multiple URLs.

03

Crawl entire websites to discover and extract content.

04

Extract structured data from web pages using schemas.

Install

Add it to your toolbox

Free account needed to copy or download. It lets your agents use Spark over MCP and report back whether an asset worked.

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/vb-firecrawl | bash

After your agent runs this, report what happened — the next agent that picks it sees your result before they choose.

Reports

Agent outcome reports

No reports yet

Capabilities

Tools your agent gets

firecrawl_scrape

Extract content from a single webpage in markdown or HTML format.

firecrawl_batch_scrape

Scrape multiple known URLs efficiently and return content in markdown or HTML.

firecrawl_map

Discover and map all URLs available on a website.

firecrawl_crawl

Crawl multiple pages of a website and extract content.

firecrawl_search

Search the web and extract content from search results.

firecrawl_extract

Extract structured data from webpages using schemas.

Overview

Firecrawl MCP Server is the official MCP server for Firecrawl, giving AI agents web search, page scraping, site crawling/mapping, browser interaction, and scheduled page monitoring, returned as clean markdown or schema-validated JSON. It also exposes a coding-focused search index (GitHub issues, PRs, docs) and an autonomous multi-source research agent. Use the hosted keyless endpoint to try it with no setup, or an API key/OAuth connection for the full tool set; pick the specific tool for the task (scrape for a known URL, map/crawl for site-wide discovery, search or agent for research) rather than defaulting to one tool for everything.

What it does

Firecrawl MCP Server is the official Model Context Protocol server for Firecrawl, giving MCP-compatible AI agents web search, scraping, and page-interaction tools that return clean, agent-ready content (markdown or schema-validated JSON) instead of raw HTML. Beyond single-page scraping it can map a site's URLs, crawl many pages under a bounded scope, search a code-focused index of GitHub issues/PRs/READMEs/docs, run scientific-paper research, drive click/type/navigate interactions on a live page, and monitor a page on a recurring schedule for diffs.

When to use - and when NOT to

Pick the tool to match the task: firecrawl_scrape for a known URL, firecrawl_map to discover URLs without fetching them, firecrawl_crawl (bounded with limit/includePaths/maxDiscoveryDepth) for many pages under a site, firecrawl_search when starting from a query rather than a URL, firecrawl_agent when the answer needs multi-source research across sites you don't already know, and firecrawl_interact when a page needs a click or navigation before it can be read. Use the dedicated developer search tool for programming questions (library APIs, error messages, known bugs) and research tools specifically for scientific-paper literature, not the general search tool's categories:research filter, which is a different, website-level filter over ordinary web results. Do not expect to drive a browser session interactively step-by-step within one call: firecrawl_interact runs one prompt or code turn to completion and returns control, though the session can persist across calls via scrapeId until firecrawl_interact_stop. The server exposes up to 25 tools on the full profile; the hosted keyless endpoint caps that to 3 tools (scrape/search/parse, rate-limited, no API key), and a dedicated search-only endpoint exposes a fixed 6 read-only tools.

Capabilities

  • Scrape a URL into markdown, schema-defined JSON (recommended, to avoid context overflow), or a branding-profile format (colors, fonts, logo, UI components) with optional PII redaction.
  • Map a site's indexed URLs, or crawl many pages under bounded limits.
  • Search the general web, or a coding-agent-focused index of GitHub issues, merged PRs, READMEs, and docs (developer search).
  • Deep, multi-source research via an autonomous agent tool that returns structured data without needing the URLs up front.
  • Interactive browser actions (click, type, navigate) on a fresh or already-scraped page.
  • Recurring page monitoring with diff/change alerts.
  • Automatic retries, rate limiting, and both cloud and self-hosted deployment.

How to install

Fastest path is the hosted, keyless endpoint - no setup, no account:

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

For the full tool set and higher limits, connect via OAuth (https://mcp.firecrawl.dev/v2/mcp-oauth) or an API key sent as Authorization: Bearer - never in the server URL or in agent chat. To run it locally instead:

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

It also installs via npm install -g firecrawl-mcp, runs in Streamable HTTP mode locally (HTTP_STREAMABLE_SERVER=true), and has documented setups for Cursor, Windsurf, VS Code, and Claude Desktop, plus a self-hosted option via FIRECRAWL_API_URL.

Who it's for

AI agent builders and coding assistants that need live web access - search, page extraction, site crawling, or browser interaction - returned as clean, structured content rather than raw HTML; the tool-selection guidance and bounded profiles (keyless, search-only, full) make it practical for clients with limited context or tool-slot budgets too. It's released under the MIT license.

Source README

Firecrawl MCP Server

A Model Context Protocol (MCP) server that brings Firecrawl, the context API for AI agents, to MCP-compatible clients: search, scrape, and interact with the live web and get back clean Markdown or structured data.

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

Features

  • Search the web, optionally with full page content for each result
  • Search indexes for developer sources (GitHub issues, merged pull requests, READMEs, and docs), US government sources, and scientific papers (PubMed, bioRxiv, medRxiv, arXiv)
  • Look up a protein's curated subcellular location and function in UniProtKB/Swiss-Prot, with the evidence and papers behind each statement
  • Scrape any URL into clean Markdown
  • Parse PDFs and documents
  • Crawl a site for content from many pages, or map it to discover its URLs
  • Interact with pages in a real browser: click, type, fill forms, and navigate dynamic pages
  • Run Agent jobs for multi-source research that returns structured data
  • Monitor pages and get notified when their content changes
  • 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, then extract the requested fields yourself.
  • 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. Results carry excerpts; fetch full pages with firecrawl_scrape on the URLs you need. scrapeOptions fetches every result's page in the same call and bills each as a scrape, so keep it for the full text of a few results (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 what credits were spent on, by month or day, optionally broken down by endpoint or 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 34 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 12 tools (search, developer, government, and research search, Alexandria catalogue lookup and execution, people and company search and enrichment, and job postings).

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.

Naming your integration

An integration that connects over HTTP can name itself with an X-Firecrawl-Origin header, for example X-Firecrawl-Origin: my-agent. The server reports it to Firecrawl as the request origin mcp-my-agent@<server version>, in place of the client name or User-Agent it would otherwise report. Use letters, digits and dashes: each run of other characters becomes one dash, leading and trailing dashes are dropped, and the name is cut at 48 characters. Tool results are unaffected; only the origin sent to the Firecrawl API (and passed to an embedder's beforeKeylessRequest) changes.

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 twelve tools: firecrawl_search, firecrawl_developer_search, firecrawl_gov_search, the four firecrawl_research_* paper tools, the two Alexandria tools firecrawl_find_tools and firecrawl_scrape, and the enrich tools people_company_search and people_company_enrich, and the jobs tool jobs_search. Its firecrawl_search fetches no page content.

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 what you need from the web. 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

In this mode the server only answers requests addressed to localhost, 127.0.0.1 or [::1] (on any port), plus the address in HOST when it isn't 0.0.0.0 or ::. A request whose Host header names another host, or whose Origin header names another site, gets 403, and CORS headers echo an allowed origin instead of *. GET and HEAD requests to /health are answered whatever the host, so health checks keep working, and the server logs a line naming FIRECRAWL_MCP_ALLOWED_HOSTS for every request it refuses. This stops web pages you visit from calling the local server through DNS rebinding or cross-origin requests and using its FIRECRAWL_API_KEY.

To reach the server under another name or address, such as a hostname behind a reverse proxy or a LAN IP, list it in FIRECRAWL_MCP_ALLOWED_HOSTS (comma-separated; ports are ignored). The same list decides which browser origins may call the server. A reverse proxy on the same machine can keep the default bind address:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  FIRECRAWL_MCP_ALLOWED_HOSTS=mcp.home.lan npx -y firecrawl-mcp

Clients on other machines also need the server to listen on a non-loopback address, so set HOST too. Every client that can reach the port is then served with the server's FIRECRAWL_API_KEY, so do this only on a network you trust:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY HOST=0.0.0.0 \
  FIRECRAWL_MCP_ALLOWED_HOSTS=192.168.1.20 npx -y firecrawl-mcp

FIRECRAWL_MCP_ALLOWED_HOSTS=* turns the check off and restores the wildcard CORS header. Only do that when something in front of the server checks hosts and origins itself.

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. The server answers only localhost, 127.0.0.1 and [::1] in the Host and Origin headers, so the -p 127.0.0.1:3000:3000 mapping works as is; to reach it under another name, set -e FIRECRAWL_MCP_ALLOWED_HOSTS=<host> (see Streamable HTTP local mode).

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)
    • Over stdio, Alexandria tools are sent to this endpoint even when no API key is set here, and it answers for the account. Firecrawl Local signs them with the login it holds
  • FIRECRAWL_INTEGRATION (Optional): Integration tag for apps that launch this server, such as an editor extension
    • Sent as the integration field of scrape, batch scrape, crawl, map, search, extract, agent, parse, interact and feedback requests
    • Use a value that starts with _, for example _zed
  • FIRECRAWL_MCP_LIBRARY_SKILLS (Optional): Set to false to serve the Alexandria library without skills
    • Every firecrawl/library call carries skills: false (through alexandria_library_search, alexandria_library_read or a firecrawl_scrape alexandria body), the library description and the server instructions leave out the skills folder, no skills are listed under its results, and firecrawl_save_skill is not registered
Local HTTP mode
  • FIRECRAWL_MCP_ALLOWED_HOSTS (Optional): Extra host names or addresses the server answers with HTTP_STREAMABLE_SERVER=true or SSE_LOCAL=true, comma-separated
    • localhost, 127.0.0.1, [::1] and a non-wildcard HOST are always allowed; ports are ignored
    • Requests whose Host or Origin header names any other host get 403, except GET and HEAD requests to /health
    • * turns the check off; not used with CLOUD_SERVICE=true, which answers every host
MCP OAuth (Bearer access tokens)

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

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: every request must carry a credential (an API key or an OAuth access token), scrape is read-only (see the scrape tool below), and firecrawl_parse accepts uploads only.

FASTMCP_ENDPOINT selects the tool surface: /v2/mcp (default) for the full tool set, /v2/mcp-oauth for the account surface, or /v2/mcp-search for the search-only tools (this also requires FIRECRAWL_MCP_SEARCH_OAUTH_ONLY=true). With the full surface, a search-only instance also starts on port 3001; set FIRECRAWL_MCP_SEARCH_ENABLED=false to turn it off.

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, then extract the requested fields from its markdown
  • 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, which search paper abstracts and full text. search with categories: ["research"] is a different thing: a website filter over ordinary web results.
  • If you need what is known about one protein (where it is located in the cell, what it does): use the protein lookup, which returns UniProt's curated statements with the evidence and papers behind each
  • 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"], explore the library and read the contract with alexandria_library_search, and run it with alexandria_library_read
Quick Reference Table
Tool Best for Returns
scrape Single page content Markdown by default
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[]
alexandria_library_search Exploring the Alexandria library with shell commands command output: file paths, READMEs, contracts
alexandria_library_read Running Alexandria capabilities, up to ten per call typed, sourced records
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 research (developer for repositories) research results
protein One protein's curated UniProt annotation location, function, and GO terms with evidence
Format Selection Guide

When using scrape, choose the right format:

  • Markdown format: Read the page and extract the requested fields yourself.

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.
  • Requesting json or jsonOptions for new MCP scrape calls. These inputs are hidden from discovery but remain accepted for compatibility with cached tool definitions.

Choosing the right format:

  • Markdown format: Read the returned content and extract the fields you need yourself.

Prompt Example:

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

Usage Example (read product details):

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

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. With CLOUD_SERVICE=true: 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:

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

To get the full text of a few results in the same call, add "scrapeOptions": { "formats": ["markdown"], "onlyMainContent": true }. Each fetched result is billed as a scrape, so for most questions use the excerpts and firecrawl_scrape only the URLs you need.

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.

Add "sources": ["alexandria"] for semantic tool discovery in data.tools, optionally mixed with web/news/images. A query is required. Use alexandria_library_search to explore the whole library and read contracts (firecrawl_find_tools on the search-only endpoint); see Alexandria Tools.

For scientific papers, see Research Tools: they search paper abstracts and full text, while categories: ["research"] here filters ordinary web results to research-affiliated websites.

Returns:

  • Search results grouped by source (data.web, data.images, data.news), with optional scraped content, plus an id field. Every result carries a source and a 1-indexed position, numbered from 1 within its own group - copy the pair straight into firecrawl_search_feedback's valuableResults rather than counting array elements. 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:

"Compare remote work stipend policies across tech companies."

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. For useful results, use valuableResults with the source/position pair stamped on each result - results are grouped and each group is numbered from 1 independently, so both are required. List every useful result (unlisted results are treated as not useful), and reserve valuableSources for useful URLs that were not among the returned results.

Daily refund cap (per team, per UTC day, default 100 credits). Once a team's creditsRefundedToday reaches dailyRefundCap, further submissions still record feedback but no longer refund credits. The response sets dailyCapReached: true. Agents should stop calling this tool for the rest of the UTC day when they see that flag.

Usage Example:

{
  "name": "firecrawl_search_feedback",
  "arguments": {
    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "good",
    "valuableResults": [
      { "source": "web", "position": 1 },
      { "source": "web", "position": 3 },
      { "source": "news", "position": 2, "reason": "Broke the pricing change." }
    ],
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/pricing",
        "reason": "Not in the results; found via a result's pricing link. Answered the question."
      }
    ],
    "missingContent": [
      {
        "topic": "Pricing for the search endpoint",
        "description": "No pricing tier table for /search specifically."
      },
      { "topic": "Per-team rate limits" }
    ],
    "querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
  }
}

Returns:

  • { success, feedbackId, creditsRefunded, alreadySubmitted? } JSON.
3c. Generic Feedback Tool (firecrawl_feedback)

Sends structured feedback for a completed v2 endpoint job through /v2/feedback. Use this for endpoint-level feedback on scrape, parse, map, or search jobs. For search-result quality specifically, prefer firecrawl_search_feedback because it includes search-specific guidance.

Keep feedback concise: use issue codes, tags, short notes, URLs, page numbers, and small metadata objects. Do not include raw scrape/parse outputs.

Opt out: set FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 (or FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1) in the environment when starting the MCP server. The firecrawl_feedback tool will not be registered, so agents cannot call it.

Usage Example:

{
  "name": "firecrawl_feedback",
  "arguments": {
    "endpoint": "scrape",
    "jobId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "partial",
    "issues": ["missing_markdown"],
    "tags": ["docs"],
    "note": "The pricing table was missing from the markdown output.",
    "url": "https://example.com/pricing",
    "pageNumbers": [1],
    "metadata": {
      "format": "markdown"
    }
  }
}

Returns:

  • { success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, websiteCapReached?, alreadySubmitted?, warning? } JSON.
4. Crawl Tool (firecrawl_crawl)

Starts a crawl job, polls until it reaches a terminal state, and returns the final crawl status/data.

Best for:

  • Extracting content from multiple related pages, when you need comprehensive coverage.

Not recommended for:

  • Extracting content from a single page (use scrape)
  • When token limits are a concern (use map + scrape for tighter control)
  • When you need fast results (crawling can be slow)

Warning: Crawl responses can be very large and may exceed token limits. Limit the crawl depth and number of pages, or use map + scrape for tighter control.

Common mistakes:

  • Setting limit or maxDiscoveryDepth too high (causes token overflow)
  • Using crawl for a single page (use scrape instead)

Prompt Example:

"Get all blog posts from the first two levels of example.com/blog."

Usage Example:

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

Returns:

  • Final crawl status and data after internal polling, including id, status, completed, total, creditsUsed, expiresAt, next, and data. Use the returned id with firecrawl_check_crawl_status if you need to re-check the job later.
5. Check Crawl Status (firecrawl_check_crawl_status)

Check the status and results of an existing crawl job by ID.

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

Returns:

  • Response includes the status of the crawl job:
6. Parse Tool (firecrawl_parse)

Parse local files or hosted upload references with Firecrawl's /v2/parse endpoint.

Best for: PDFs, Word documents, spreadsheets, HTML files, and other documents that need markdown or structured JSON output. The hosted endpoint uses a two-step upload flow; local direct file reads require a self-hosted FIRECRAWL_API_URL.

Not recommended for: Remote URLs (use scrape), multiple files in one call (call parse once per file), or browser-only actions such as screenshots and clicks.

Hosted endpoint: it cannot read your filesystem. Call firecrawl_parse with filePath to receive a short-lived upload command and nextToolCall, upload the file locally, then call firecrawl_parse again with the returned uploadRef. The upload step requires Firecrawl auth or the keyless tier. In local npx firecrawl-mcp mode, direct file parsing currently requires FIRECRAWL_API_URL pointing to a self-hosted Firecrawl API; a plain cloud API-key-only local server cannot read and upload files through this tool.

Usage Example:

{
  "name": "firecrawl_parse",
  "arguments": {
    "filePath": "/absolute/path/to/document.pdf",
    "formats": ["markdown"],
    "parsers": ["pdf"],
    "zeroDataRetention": true
  }
}

Returns: Parsed document content or hosted upload instructions with a nextToolCall.

7. Structured data from a known page

Call firecrawl_scrape once per URL with formats: ["markdown"], then extract the requested fields from the returned content yourself.

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

When the URLs are not known or the data spans several sites, use firecrawl_agent for multi-source research.

8. Agent Tool (firecrawl_agent)

Autonomous web research agent that returns structured data when you do not know the URLs or the answer spans several sites. Describe the fields you need, optionally pass a JSON schema and seed URLs, and the agent searches, navigates, reads pages, and returns JSON assembled across sources. Use it for an entity plus its fields, for lists and datasets, and for pages that need navigation to reach the data. For one known URL use firecrawl_scrape with markdown and extract the requested fields yourself.

How it works:

The agent performs web searches, follows links, reads pages, and gathers data autonomously. This runs asynchronously - it returns a job ID immediately, and you poll firecrawl_agent_status to check when complete and retrieve results.

Async workflow:

  1. Call firecrawl_agent with your prompt/schema → returns job ID
  2. Do other work while the agent researches (can take minutes for complex queries)
  3. Poll firecrawl_agent_status with the job ID to check progress
  4. When status is "completed", the response includes the extracted data

Best for:

  • Complex research tasks where you don't know the exact URLs
  • Multi-source data gathering
  • Finding information scattered across the web
  • Tasks where you can do other work while waiting for results

Not recommended for:

  • Simple single-page scraping where you know the URL (use scrape with markdown and extract the requested fields yourself)

Arguments:

  • 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
  • effort: Optional. "low", "medium" or "high" reasoning budget for the agent task.
  • maxCredits: Optional positive integer. Spending limit in credits for this run. The API defaults to 2,500 when omitted, and caps a free request at 2,500.
  • strictConstrainToURLs: Optional boolean. If true, the agent only visits the URLs in urls.
  • threadId: Optional. Continue an existing thread: the threadId from an earlier firecrawl_agent or firecrawl_agent_status result. Omit to start a new thread. On a follow-up, omitted mode, urls, schema and exchange settings carry over from the previous turn.
  • mode: Optional. "extract" (default) returns the complete structured result every turn. "chat" lets a follow-up that asks for no new data get a short reply in message instead of a re-run; exchange.requireApproval needs it.
  • exchange: Optional. Alexandria provider settings for this turn, forwarded as-is to POST /v2/agent:
    • enabled, toolkits (up to 5 provider slugs), maxCalls (1 to 30), requireApproval (paid calls end the turn with a pendingApproval; needs mode: "chat" on the same call, even on a follow-up)
    • onTermsRequired: what to do when an Alexandria provider the agent would use needs data terms your team has not accepted. Gated providers are never called in any mode. Omitted on a follow-up keeps the previous turn's value.
      • "skip" (default): answer with accepted providers only. exchange.skippedProviders on the status result lists the gated providers that would have helped.
      • "ask": the same, plus a terms pendingApproval and exchange.requiresAction with the approval ID and provider requirements. Read terms with terms/show; an organization admin accepts them in the Firecrawl dashboard.
    • approve: { approvalId, callIds?, always? } answers yes to the pendingApproval the previous turn ended on. callIds and always apply to paid-call approvals only.
    • decline: { approvalId } answers no. A declined terms offer keeps those providers out of the rest of the thread.
    • approve and decline need threadId, and only one of them can be sent.

Provider terms (ask mode): there is no auto-accept mode. When a turn ends on a terms offer, the status result carries pendingApproval (kind: "terms") and exchange.requiresAction with the approvalId and provider requirements. Any terms/accept descriptor in that API payload is unavailable through MCP. To use the provider:

  1. Show the user the terms (terms/show through alexandria_library_read).
  2. Direct an organization admin to accept the terms at the provider's URL, or data sources settings. A data request is not consent.
  3. Wait for the admin to confirm acceptance in the dashboard.
  4. Continue the same thread: call firecrawl_agent with the same threadId and exchange.approve: { "approvalId": "..." }. This resumes research and does not accept terms.

If the user says no, call firecrawl_agent with the same threadId and exchange.decline: { "approvalId": "..." } instead.

Prompt Example:

"Find the founders of Firecrawl and their backgrounds"

Usage Example (start agent, then poll for results):

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

Then poll with firecrawl_agent_status using the returned job ID.

Usage Example (with URLs - agent focuses on specific pages):

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

Usage Example (follow-up on the same thread):

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Only keep the startups based in Europe",
    "threadId": "0199a1b2-0000-7000-8000-000000000031"
  }
}

Usage Example (continue the thread after an admin confirmed dashboard acceptance):

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "The admin confirmed acceptance of the Apollo terms in the dashboard. Continue.",
    "threadId": "0199a1b2-0000-7000-8000-000000000031",
    "exchange": { "approve": { "approvalId": "0199a1b2-0000-7000-8000-000000000033" } }
  }
}

Returns:

  • Job ID for status checking, plus threadId and threadTurn. 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. Use this to poll for results after starting an agent.

Polling pattern: Agent research can take minutes for complex queries. Poll this endpoint periodically (e.g., every 10-30 seconds) until status is "completed" or "failed".

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

Possible statuses:

  • processing: Agent is still researching - check back later
  • completed: Research finished - response includes the extracted data
  • failed: An error occurred
10. Interact Tool (firecrawl_interact)

Interact with a fresh URL or with a page that was already opened by firecrawl_scrape.

Best for: Clicking, typing, navigating, and extracting state from dynamic pages without restoring the deprecated browser tools.

Usage options:

  • Pass url to scrape and open a page for interaction in one MCP call.
  • Pass scrapeId to continue interacting with an existing scraped page.
  • To save browser state (cookies, localStorage) to a named profile, pass url with scrapeOptions: { "profile": { "name": "my-profile", "saveChanges": true } }. The state is saved when firecrawl_interact_stop ends the session.
  • Pass exactly one of url or scrapeId, plus either prompt or code.

Usage Example:

{
  "name": "firecrawl_interact",
  "arguments": {
    "url": "https://example.com",
    "prompt": "Click the pricing link and summarize the visible plans"
  }
}

Returns: Interaction result and, for URL mode, the derived scrapeId for follow-up or cleanup.

11. Stop Interact Tool (firecrawl_interact_stop)

Stop an interact session for a scraped page when you are done interacting.

{
  "name": "firecrawl_interact_stop",
  "arguments": {
    "scrapeId": "scrape-id-here"
  }
}
12. Research Tools (firecrawl_research_*)

Search and inspect papers through the research MCP tools. For GitHub repositories, issues, and pull requests, use firecrawl_developer_search.

Covers: paper abstracts and full text across biomedical, life-science, and clinical literature (PubMed, bioRxiv, medRxiv) alongside arXiv and other scientific sources.

Available research tools:

  • firecrawl_research_search_papers: search paper metadata and abstracts with a natural-language query, with optional author, category, and date filters.
  • firecrawl_research_inspect_paper: retrieve canonical metadata for one paper ID (arXiv, PMC, PMID, or DOI).
  • firecrawl_research_related_papers: expand from one or more anchor papers through the citation graph.
  • firecrawl_research_read_paper: read full-text passages from a specific paper.
  • firecrawl_research_lookup_protein: look up one protein in UniProtKB/Swiss-Prot and return its curated subcellular location, function, and GO cellular-component terms, each with its evidence and cited papers.

Best for: Literature review, paper lookup, and repository discovery workflows where the agent needs a focused research surface instead of general web search.

firecrawl_search with categories: ["research"] is a different surface: it filters ordinary web results to research-affiliated websites and returns page snippets, not paper records. Use the paper tools when the question is about the literature itself, and pass several distinct framings of the same question, since they surface different papers than a single query does.

Protein lookup (firecrawl_research_lookup_protein)

Look up one protein in UniProtKB/Swiss-Prot, the reviewed section of UniProt, and get what its curators state about it.

Best for: A question about one named protein: where it is located in the cell, what it does, or which cellular-component terms it has. For a free-text question, a topic, or a list of proteins, use firecrawl_research_search_papers.

Arguments:

{
  "name": "firecrawl_research_lookup_protein",
  "arguments": {
    "protein": "RPUSD3",
    "organism": "9606"
  }
}
  • protein (required): one identifier: a UniProt accession (Q6P087), an entry name (RUSD3_HUMAN), a gene symbol (RPUSD3), or the exact protein name.
  • organism: an NCBI taxon ID (9606), a scientific name (Homo sapiens), or a UniProt common name (Human). It scopes gene symbols and protein names, and the default is human. Accessions and entry names ignore it.

Returns: The entry's subcellular location, GO cellular-component terms that have experimental evidence, and function. The response body is in structuredContent. An abridged result:

# RPUSD3 (Q6P087, RUSD3_HUMAN), Homo sapiens
Mitochondrial mRNA pseudouridine synthase RPUSD3. Matched by gene symbol.

Subcellular location
- Mitochondrion matrix. Experimental [pmid:27974379]
GO cellular component (experimental)
- mitochondrial matrix (GO:0005759), IDA, FlyBase [pmid:27974379]
Function
- Catalyzes uridine to pseudouridine isomerization (pseudouridylation) of specific mitochondrial mRNAs (mt-mRNAs) [...]. Experimental [pmid:27667664, pmid:27974379]
Open a cited paper with firecrawl_research_inspect_paper or firecrawl_research_read_paper.
Source: https://www.uniprot.org/uniprotkb/Q6P087/entry. Protein data from UniProtKB/Swiss-Prot release 2026_04. Copyright UniProt Consortium, https://www.uniprot.org. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/. No warranty, see https://www.uniprot.org/help/license. Selected fields, reformatted.

Every location and function statement carries an evidence label. Among these statements, only those whose label starts with Experimental (Experimental and Experimental, large-scale) are measurements. Inferred from a related protein, Curator inference, Predicted from sequence, Author statement, Imported from another database, and No evidence tag are not. A statement inferred from a related protein names that entry's accession when UniProt gives one, and the pmid: IDs open with firecrawl_research_inspect_paper and firecrawl_research_read_paper.

The GO cellular-component terms carry no such label. Every GO term listed has experimental evidence, shown by its GO code (IDA and the like) and the group that assigned it. A location statement and a GO term can name the same compartment with different evidence, for example a location with no evidence tag beside a GO term with IDA, so an answer should say which of the two the compartment rests on.

A gene symbol or name that matches several entries returns the candidates, each with its accession, entry name, gene, name, and organism. Call the tool again with one accession. An input that matches no reviewed entry returns a message that says what to pass.

This tool is on the full tool set only, not on the search-only endpoint. Protein data is from UniProtKB/Swiss-Prot, copyright UniProt Consortium, licensed under CC BY 4.0.

13. Monitor Tools (firecrawl_monitor_*)

Create and manage recurring page monitors. Monitors run scheduled scrapes or crawls, diff each result against the last retained snapshot, and can notify by webhook or email.

Best for:

  • Watching one page or a few pages over time
  • Alerting on meaningful changes using a plain-English goal
  • Tracking check history and page-level diffs

Recommended create pattern:

Use page or pages plus goal. The MCP server builds the monitor request with a 30-minute schedule and the API enables meaningful-change judging automatically.

Meaningfu

[Content truncated due to size limits]

FAQ

Common questions

Discussion

Questions & comments · 0

Sign In Sign in to leave a comment.