firecrawl/firecrawl-mcp-server for MCP | Awesome Skills
Decision brief
What problem does Firecrawl MCP Server solve?
Firecrawl MCP Server is useful when an AI client needs to gather web evidence as part of a real task, rather than relying on a remembered answer or a hand-pasted page. The project positions itself as Firecrawl's official MCP integration for web search and page extraction. Its documented scope is broad enough to cover a few distinct jobs: discovering relevant sources, retrieving a particular page in structured form, exploring a bounded site, and taking a browser-like action when a static request is insufficient. That breadth matters because a research request usually contains more than one of those jobs, even when the user asks a short question.
The decision value is not simply that an agent can access the web. It is that the workflow can choose an operation that matches the available information. A known product URL calls for a different request than a question that starts with only a topic, and both differ from a task that needs navigation or a wider site inventory. The repository explicitly separates scrape, map, search, agent, crawl, and interact in its guidance. Treat those as separate capabilities with separate cost, latency, and data-handling expectations rather than as interchangeable buttons.
For a team, the attractive use case is a repeatable evidence-gathering loop: find sources, retrieve only the pages needed, inspect the returned material, and let a human decide what belongs in the final answer or action. This server can provide the web-facing part of that loop to compatible clients. It does not establish whether a retrieved page is authoritative, current, permitted for a particular purpose, or appropriate to disclose. Those remain product and organizational decisions.
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Begin by classifying the request before giving the client a general instruction to research. If the team already has the target page, use the single-page path and inspect the resulting structure. If the task begins with a site but not a page, use mapping to establish the available surface. If the target itself is unknown, start with search. The documented selection guide provides this separation, and it gives a practical way to make prompts more predictable: the agent should state what it knows, choose the matching tool, and explain why that tool is adequate for the next step.
A good first workflow is source collection for a human-reviewed brief. For example, an analyst can supply a shortlist of known vendor pages, have the client extract each one, and ask it to identify gaps that still require search. The team can then compare citations with the original pages before adopting any conclusion. This keeps the server's role specific and observable. It also prevents a common failure mode in which an agent begins a broad crawl when the question could have been answered with two inspected documents.
Do not treat a scrape call as a batch crawler. The server documents its scrape tool as a one-page operation, with different approaches for multiple URLs or site-wide work. That boundary should influence prompt design and quotas. Ask for a bounded list of pages, require an intermediate summary before expanding scope, and use crawling only when the project has stated what part of a site is relevant. For complex, open-ended research, the documented agent capability may be useful, but it should be piloted with a clear output standard and a stop condition rather than left to run without review.
Select the operating model before rolling the server into a shared client configuration. The documentation describes a hosted MCP endpoint and also allows a custom API URL for a self-hosted Firecrawl service. The hosted route has a keyless, rate-limited starting tier for a limited set of functions, while broader tools require an API key. That makes the keyless tier suitable for checking client compatibility and basic request shape, not for assuming that a production research workload has no identity, quota, or cost implications.
For a sustained deployment, decide where credentials live and which workloads may send content to the selected endpoint. The cloud configuration uses FIRECRAWL_API_KEY by default; a self-hosted endpoint changes the operational boundary but still needs explicit ownership, network access, updates, and failure handling. Keep the key outside shared client configuration, provision it with a scope and rotation process appropriate to the team, and test the exact client that will invoke the tools. A configuration that works in one desktop client is not evidence that every MCP host handles authentication or tool responses the same way.
Instrument the pilot before measuring usefulness. The server documents operation and progress logs, performance metrics, rate-limit tracking, and error conditions. Use those signals to answer practical questions: are agents requesting more pages than the task warrants, are limits interrupting an important workflow, and can reviewers understand where a result came from? Rate-limit errors are documented as feedback to the MCP client, so the calling workflow should surface a partial result and a clear next action instead of silently retrying until it creates an opaque failure.
Do not add this integration merely because an agent occasionally needs one public page. A browser bookmark, a direct API request, or a manually maintained source list may be simpler when the work is rare and the answer is easy to verify. An MCP connection adds client configuration, credentials for many useful operations, rate behavior, and a new path through which an agent can request external data. It earns that complexity when web retrieval is frequent enough that consistent tool selection and observability save meaningful effort.
It is also a poor fit for a workflow that cannot define its retrieval boundary. The project offers tools for a known page, site discovery, web search, deeper research, site crawling, and interactive navigation. That flexibility is valuable only when a team can say which mode is appropriate for a request. If a prompt only says research everything, the client has no reliable stopping rule and reviewers cannot judge whether the result is comprehensive or merely plausible. Establish page limits, site limits, an expected source type, and a human approval step before enabling broader operations.
Avoid assuming the free hosted path will cover a full workflow. The documentation limits keyless access to selected functions and labels it rate-limited; several wider-scope tools require a key. Conversely, do not self-host solely to avoid a credential decision unless the team is prepared to operate the endpoint. The correct choice is driven by the task's required tools, the data boundary, and the operational capacity to monitor failures, not by the shortest initial installation path.
Run a small comparison using questions whose evidence can be checked independently. Give one pilot a known URL, another a known domain with an unknown page, and a third a topic requiring web discovery. Require the client to identify the chosen operation before it runs, retain the returned page references, and stop after the agreed scope. The expected pattern is straightforward: page extraction for the first case, mapping for the second, and search for the third. This tests whether the integration improves tool choice rather than merely producing fluent summaries.
Next, test the access model that matches the intended environment. A hosted, keyless experiment can validate basic compatibility with scrape, search, and interact, accepting its rate limits. A production pilot that needs crawling, mapping, deeper research, or extraction should use an approved authentication path and a written quota. If self-hosting is under consideration, repeat the same workflow through the configured custom endpoint and compare reliability, latency, maintenance responsibility, and the quality of error feedback. Do not select an operating model solely from a setup screenshot.
Adopt the server for workloads where the pilot demonstrates three things: the agent consistently selects a bounded tool for the task, reviewers can trace and assess the gathered material, and operational signals make limits and failures actionable. Keep prompts explicit about known URLs and allowed expansion. For high-impact conclusions, retain human source review even after the integration has proved useful. Firecrawl MCP Server can make web evidence available where the work already happens, but its real value depends on disciplined retrieval, not on maximizing the number of pages an agent can touch.
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:
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
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:
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).
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."
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 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",
"valuableSources": [
{
"url": "https://docs.firecrawl.dev/features/search",
"reason": "Most up-to-date description of /search."
}
],
"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'"
}
}
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"
}
}
}
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."
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.
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. Hosted MCP supports a two-step upload-ref 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 MCP flow: Hosted MCP cannot read the caller's filesystem directly. 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. Minting the hosted upload URL requires Firecrawl auth or keyless eligibility. 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.
Returns: Parsed document content or hosted upload instructions with a nextToolCall.
7. Extract Tool (firecrawl_extract)
Extract structured information from web pages using LLM capabilities. Supports both cloud AI and self-hosted LLM extraction.
Best for:
Extracting specific structured data like prices, names, details.
Not recommended for:
When you need the full content of a page (use scrape)
When you're not looking for specific structured data
Arguments:
urls: Array of URLs to extract information from
prompt: Custom prompt for the LLM extraction
systemPrompt: System prompt to guide the LLM
schema: JSON schema for structured data extraction
allowExternalLinks: Allow extraction from external links
enableWebSearch: Enable web search for additional context
includeSubdomains: Include subdomains in extraction
When using a self-hosted instance, the extraction will use your configured LLM. For cloud API, it uses Firecrawl's managed LLM service.
Prompt Example:
"Extract the product name, price, and description from these product pages."
Extracted structured data as defined by your schema
{
"content": [
{
"type": "text",
"text": {
"name": "Example Product",
"price": 99.99,
"description": "This is an example product description"
}
}
],
"isError": false
}
8. Agent Tool (firecrawl_agent)
Autonomous web research agent. This is a separate AI agent layer that independently browses the internet, searches for information, navigates through pages, and extracts structured data based on your query.
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:
Call firecrawl_agent with your prompt/schema → returns job ID
Do other work while the agent researches (can take minutes for complex queries)
Poll firecrawl_agent_status with the job ID to check progress
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 JSON format - faster and cheaper)
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
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"
}
}
Returns:
Job ID for status checking. 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".
Best for: Literature review, paper lookup, and repository discovery workflows where the agent needs a focused research surface instead of general web scraping.
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.
Meaningful-change judging runs automatically when goal is set. Page webhooks expose isMeaningful and judgment on monitor.page events.
Write goals as concise 2-3 sentence monitor instructions. Say what should trigger an alert, preserve any scope the user gave, and include intent-specific exclusions only when obvious from the request. Generic noise such as whitespace, formatting-only changes, request IDs, tracking params, generic metadata, and unrelated page chrome is already handled by the judge, so do not repeat it in every goal. If the user is vague, keep the goal broad; if they ask for broad monitoring or "any change", preserve that. If the user says they do not care about something, include that explicitly.
{
"name": "firecrawl_monitor_create",
"arguments": {
"page": "https://example.com/pricing",
"goal": "Alert when pricing, packaging, or launch messaging changes."
}
}
firecrawl_monitor_update: update fields including goal, judgeEnabled, webhook, and notification.
firecrawl_monitor_run: trigger a check now.
firecrawl_monitor_delete: delete a monitor (destructive; only call when the user intends to remove it).
firecrawl_monitor_checks: list checks, optionally filtered by status.
firecrawl_monitor_check: get page-level results, including diff, snapshot, judgment.meaningful, and judgment.meaningfulChanges.
fcr_…
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
