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!
- 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)
- Scrape any URL into clean Markdown or structured JSON
- 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.
- Use
firecrawl_scrapewhen you have a known URL and want its content as markdown or as JSON matching a schema you supply. - Use
firecrawl_mapwhen you need to discover URLs on a site without fetching their content. - Use
firecrawl_crawlwhen you need content from many pages under a site; setlimit,includePaths/excludePaths, ormaxDiscoveryDepthto bound it. - Use
firecrawl_searchwhen you're starting from a query rather than a URL and want ranked web results. Results carry excerpts; fetch full pages withfirecrawl_scrapeon the URLs you need.scrapeOptionsfetches 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_interactwhen a page needs a click, type, or navigate action before you can read it: pass aurlfor a fresh page or ascrapeIdto 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_usageto 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_interactcall runs onepromptorcodeturn to completion and returns control. The session can persist across calls viascrapeIdand ends withfirecrawl_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).
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.
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.
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.
env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcpnpm install -g firecrawl-mcpConfiguring 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
- Open Cursor Settings
- Go to Features > MCP Servers
- Click "+ Add new global MCP server"
- 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
- Open Cursor Settings
- Go to Features > MCP Servers
- Click "+ Add New MCP Server"
- 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.
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"
}
}
}
}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-mcpUse 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-mcpClients 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-mcpFIRECRAWL_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.
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:latestThe 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).
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}"
}
}
}
}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)
- Example:
FIRECRAWL_INTEGRATION(Optional): Integration tag for apps that launch this server, such as an editor extension- Sent as the
integrationfield of scrape, batch scrape, crawl, map, search, extract, agent, parse, interact and feedback requests - Use a value that starts with
_, for example_zed
- Sent as the
FIRECRAWL_MCP_ALLOWED_HOSTS(Optional): Extra host names or addresses the server answers withHTTP_STREAMABLE_SERVER=trueorSSE_LOCAL=true, comma-separatedlocalhost,127.0.0.1,[::1]and a non-wildcardHOSTare always allowed; ports are ignored- Requests whose
HostorOriginheader names any other host get403, exceptGETandHEADrequests to/health *turns the check off; not used withCLOUD_SERVICE=true, which answers every host
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, orSSE_LOCAL=true): Clients should sendAuthorization: Bearer <fco_access_token>on MCP requests. An OAuth bearer token takes precedence overx-firecrawl-api-key/x-api-keywhen both are present. - stdio: Use
FIRECRAWL_OAUTH_TOKENfor a static access token, or keep usingFIRECRAWL_API_KEYfor 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 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.
For cloud API usage:
export FIRECRAWL_API_KEY=your-api-keyFor 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 authAdd 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"
}
}
}
}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, which search paper abstracts and full text.
searchwithcategories: ["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 scrapealexandria
| 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 research (developer for repositories) | research results |
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 summarizatio