Firecrawl MCP 服务器

这是一个与 Firecrawl 集成的模型上下文协议 (MCP) 服务器实现，用于提供网页抓取功能。

非常感谢 @vrknetha 和 @knacklabs 的初始实现！

功能

• 网页抓取、爬行和发现
• 搜索和内容提取
• 深度研究和批量抓取
• 自动重试和速率限制
• 云端和自托管支持
• SSE 支持

在 MCP.so 的 playground 或 Klavis AI 上体验我们的 MCP 服务器。

安装

使用 npx 运行

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

手动安装

bash
npm install -g firecrawl-mcp

在 Cursor 上运行

配置 Cursor 🖥️
注意：需要 Cursor 版本 0.45.6 及以上
有关最新配置说明，请参阅官方 Cursor 文档中的 MCP 服务器配置指南：
Cursor MCP 服务器配置指南

在 Cursor v0.48.6 中配置 Firecrawl MCP

1. 打开 Cursor 设置
2. 转到功能 > MCP 服务器
3. 点击“+ 添加新的全局 MCP 服务器”
4. 输入以下代码：
   json
   {
   "mcpServers": {
   "firecrawl-mcp": {
   "command": "npx",
   "args": ["-y", "firecrawl-mcp"],
   "env": {
   "FIRECRAWL_API_KEY": "YOUR-API-KEY"
   }
   }
   }
   }

在 Cursor v0.45.6 中配置 Firecrawl MCP

1. 打开 Cursor 设置
2. 转到功能 > MCP 服务器
3. 点击“+ 添加新的 MCP 服务器”
4. 输入以下内容：
   • 名称: "firecrawl-mcp"（或您喜欢的名称）
   • 类型: "command"
   • 命令: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

如果您使用的是 Windows 并遇到问题，请尝试 cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"

将 your-api-key 替换为您的 Firecrawl API 密钥。如果您还没有密钥，可以在 https://www.firecrawl.dev/app/api-keys 创建一个账户并获取。

添加后，刷新 MCP 服务器列表以查看新工具。Composer Agent 将在适当的时候自动使用 Firecrawl MCP，但您也可以通过描述您的网页抓取需求来显式请求它。通过 Command+L（Mac）访问 Composer，在提交按钮旁边的“代理”中选择，并输入您的查询。

在 Windsurf 上运行

将以下内容添加到您的 ./codeium/windsurf/model_config.json 文件中：

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

以 SSE 本地模式运行

要使用 Server-Sent Events (SSE) 本地运行服务器而不是默认的 stdio 传输方式：

bash
env SSE_LOCAL=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp

使用 URL: http://localhost:3000/sse

通过 Smithery（旧版）安装

要通过 Smithery 自动为 Claude Desktop 安装 Firecrawl：

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

在 VS Code 上运行

单击下面的其中一个安装按钮进行一键安装...

对于手动安装，请将以下 JSON 块添加到您的 VS Code 用户设置（JSON）文件中。您可以通过按 Ctrl + Shift + P 并键入 Preferences: Open User Settings (JSON) 来完成此操作。

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

可选地，您可以将其添加到工作区中的 .vscode/mcp.json 文件中。这将允许您与他人共享配置：

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

配置

环境变量

云 API 所需

• FIRECRAWL_API_KEY: 您的 Firecrawl API 密钥
  • 使用云 API 时必需（默认）
  • 当使用自托管实例并提供 FIRECRAWL_API_URL 时可选
• FIRECRAWL_API_URL（可选）：自托管实例的自定义 API 端点
  • 示例：https://firecrawl.your-domain.com
  • 如果未提供，则将使用云 API（需要 API 密钥）

可选配置

重试配置

• FIRECRAWL_RETRY_MAX_ATTEMPTS: 最大重试次数（默认：3）
• FIRECRAWL_RETRY_INITIAL_DELAY: 第一次重试前的初始延迟（以毫秒为单位，默认：1000）
• FIRECRAWL_RETRY_MAX_DELAY: 重试之间的最大延迟（以毫秒为单位，默认：10000）
• FIRECRAWL_RETRY_BACKOFF_FACTOR: 指数退避乘数（默认：2）

信用使用监控

• FIRECRAWL_CREDIT_WARNING_THRESHOLD: 信用使用警告阈值（默认：1000）
• FIRECRAWL_CREDIT_CRITICAL_THRESHOLD: 信用使用临界阈值（默认：100）

配置示例

对于使用自定义重试和信用监控的云 API：

bash

云 API 所需

export FIRECRAWL_API_KEY=your-api-key

可选重试配置

export FIRECRAWL_RETRY_MAX_ATTEMPTS=5 # 增加重试次数
export FIRECRAWL_RETRY_INITIAL_DELAY=2000 # 从 2 秒延迟开始
export FIRECRAWL_RETRY_MAX_DELAY=30000 # 最大 30 秒延迟
export FIRECRAWL_RETRY_BACKOFF_FACTOR=3 # 更激进的退避

可选信用监控

export FIRECRAWL_CREDIT_WARNING_THRESHOLD=2000 # 在 2000 信用时发出警告
export FIRECRAWL_CREDIT_CRITICAL_THRESHOLD=500 # 在 500 信用时发出严重警告

对于自托管实例：

bash

自托管所需

export FIRECRAWL_API_URL=https://firecrawl.your-domain.com

自托管的可选身份验证

export FIRECRAWL_API_KEY=your-api-key # 如果您的实例需要身份验证

自定义重试配置

export FIRECRAWL_RETRY_MAX_ATTEMPTS=10
export FIRECRAWL_RETRY_INITIAL_DELAY=500 # 从更快的重试开始### 使用 Claude Desktop

将以下内容添加到您的 claude_desktop_config.json 文件中：

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

    "FIRECRAWL_RETRY_MAX_ATTEMPTS": "5",
    "FIRECRAWL_RETRY_INITIAL_DELAY": "2000",
    "FIRECRAWL_RETRY_MAX_DELAY": "30000",
    "FIRECRAWL_RETRY_BACKOFF_FACTOR": "3",

    "FIRECRAWL_CREDIT_WARNING_THRESHOLD": "2000",
    "FIRECRAWL_CREDIT_CRITICAL_THRESHOLD": "500"
  }
}

}
}

系统配置

服务器包含多个可通过环境变量设置的可配置参数。以下是未配置时的默认值：

typescript
const CONFIG = {
retry: {
maxAttempts: 3, // 限流请求的最大重试次数
initialDelay: 1000, // 首次重试前的初始延迟（毫秒）
maxDelay: 10000, // 重试之间的最大延迟（毫秒）
backoffFactor: 2, // 指数退避的乘数
},
credit: {
warningThreshold: 1000, // 当信用使用达到此水平时发出警告
criticalThreshold: 100, // 当信用使用达到此水平时发出严重警报
},
};

这些配置控制：

1. 重试行为

   • 自动重试因限流而失败的请求
   • 使用指数退避以避免对 API 造成过大压力
   • 示例：使用默认设置，重试将在以下时间进行：
     • 第一次重试：1 秒延迟
     • 第二次重试：2 秒延迟
     • 第三次重试：4 秒延迟（不超过最大延迟）

2. 信用使用监控

   • 跟踪云 API 使用的信用消耗
   • 在指定阈值时提供警告
   • 帮助防止意外的服务中断
   • 示例：使用默认设置：
     • 在剩余 1000 个信用点时发出警告
     • 在剩余 100 个信用点时发出严重警报

速率限制和批量处理

服务器利用 Firecrawl 内置的速率限制和批量处理功能：

• 自动速率限制处理与指数退避
• 批量操作的高效并行处理
• 智能请求队列和节流
• 对于瞬态错误自动重试

如何选择工具

使用本指南选择适合您任务的正确工具：

• 如果您知道确切的 URL：
  • 单个页面：使用 scrape
  • 多个页面：使用 batch_scrape
• 如果您需要在一个网站上发现 URL： 使用 map
• 如果您想在网络上搜索信息： 使用 search
• 如果您想从页面中提取结构化数据： 使用 extract
• 如果您想分析整个站点或部分： 使用 crawl（带有限制！）
• 如果您想进行深入研究： 使用 deep_research
• 如果您想生成 LLMs.txt： 使用 generate_llmstxt

快速参考表

工具	最佳用途	返回
scrape	单页内容	markdown/html
batch_scrape	多个已知 URL	markdown/html[]
map	发现网站上的 URL	URL[]
crawl	多页提取（带有限制）	markdown/html[]
search	网络搜索信息	results[]
extract	从页面中提取结构化数据	JSON
deep_research	深入、多源研究	summary, sources
generate_llmstxt	为域生成 LLMs.txt	text

可用工具

1. 抓取工具 (firecrawl_scrape)

从单个 URL 抓取内容，并带有高级选项。

最佳用途：

• 单页内容提取，当您确切知道哪个页面包含所需信息时。

不推荐用于：- 从多个页面提取内容（对于已知URL使用batch_scrape，或者先使用map+batch_scrape发现URL，或使用crawl获取整个页面的内容）

• 当你不确定哪个页面包含所需信息时（使用search）
• 当你需要结构化数据时（使用extract）

常见错误：

• 对于一系列URL使用scrape（应改用batch_scrape）。

示例提示：

"获取https://example.com页面的内容。"

使用示例：
json
{
"name": "firecrawl_scrape",
"arguments": {
"url": "https://example.com",
"formats": ["markdown"],
"onlyMainContent": true,
"waitFor": 1000,
"timeout": 30000,
"mobile": false,
"includeTags": ["article", "main"],
"excludeTags": ["nav", "footer"],
"skipTlsVerification": false
}
}

返回：

• 按指定格式返回Markdown、HTML或其他格式的内容。

2. 批量抓取工具 (firecrawl_batch_scrape)

高效地抓取多个URL，并内置了速率限制和并行处理功能。

最适合用于：

• 当你知道要抓取的确切页面时，从多个页面检索内容。

不推荐用于：

• 发现URL（如果不知道URL，请先使用map）
• 抓取单个页面（使用scrape）

常见错误：

• 同时使用batch_scrape处理过多的URL（可能会触达速率限制或令牌溢出）

示例提示：

"获取这三个博客文章的内容：[url1, url2, url3]。"

使用示例：
json
{
"name": "firecrawl_batch_scrape",
"arguments": {
"urls": ["https://example1.com", "https://example2.com"],
"options": {
"formats": ["markdown"],
"onlyMainContent": true
}
}
}

返回：

• 响应包括用于状态检查的操作ID：

json
{
"content": [
{
"type": "text",
"text": "批量操作已排队，ID为：batch_1。请使用firecrawl_check_batch_status来检查进度。"
}
],
"isError": false
}

3. 检查批量状态 (firecrawl_check_batch_status)

检查批量操作的状态。

json
{
"name": "firecrawl_check_batch_status",
"arguments": {
"id": "batch_1"
}
}

4. 映射工具 (firecrawl_map)

映射网站以发现站点上所有索引的URL。

最适合用于：

• 在决定抓取哪些内容之前，发现网站上的URL
• 查找网站的特定部分

不推荐用于：

• 当你已经知道需要的具体URL时（使用scrape或batch_scrape）
• 当你需要页面内容时（在映射后使用scrape）

常见错误：

• 使用crawl而不是map来发现URL

示例提示：

"列出example.com上的所有URL。"

使用示例：
json
{
"name": "firecrawl_map",
"arguments": {
"url": "https://example.com"
}
}

返回：

• 网站上找到的URL数组

5. 搜索工具 (firecrawl_search)

搜索网络并可选地从搜索结果中提取内容。

最适合用于：

• 当你不知道哪个网站包含信息时，在多个网站上查找特定信息。
• 当你需要查询最相关的内容时

不推荐用于：

• 当你已经知道要抓取的网站时（使用scrape）
• 当你需要全面覆盖单一网站时（使用map或crawl）

常见错误：

• 对于开放式问题使用crawl或map（应改用search）

使用示例：
json
{
"name": "firecrawl_search",
"arguments": {
"query": "latest AI research papers 2023",
"limit": 5,
"lang": "en",
"country": "us",
"scrapeOptions": {
"formats": ["markdown"],
"onlyMainContent": true
}
}
}

返回：

• 搜索结果数组（可选地包含抓取的内容）

示例提示：

"查找2023年发布的最新AI研究论文。"

6. 爬虫工具 (firecrawl_crawl)

开始对网站进行异步爬取作业，并从所有页面中提取内容。

最适合用于：

• 当你需要全面覆盖时，从多个相关页面提取内容。不推荐用于：
• 从单个页面提取内容（请使用 scrape）
• 当令牌限制是一个问题时（请使用 map + batch_scrape）
• 当你需要快速结果时（爬取可能很慢）

警告： 爬取响应可能非常大，并且可能会超出令牌限制。限制爬取深度和页面数量，或者使用 map + batch_scrape 以获得更好的控制。

常见错误：

• 将 limit 或 maxDepth 设置得太高（会导致令牌溢出）
• 对于单个页面使用 crawl（请改用 scrape）

提示示例：

"获取 example.com/blog 前两级的所有博客文章。"

使用示例：
json
{
"name": "firecrawl_crawl",
"arguments": {
"url": "https://example.com/blog/*",
"maxDepth": 2,
"limit": 100,
"allowExternalLinks": false,
"deduplicateSimilarURLs": true
}
}

返回：

• 响应包括用于状态检查的操作 ID：

json
{
"content": [
{
"type": "text",
"text": "已开始爬取: https://example.com/*，任务ID为: 550e8400-e29b-41d4-a716-446655440000。使用 firecrawl_check_crawl_status 检查进度。"
}
],
"isError": false
}

7. 检查爬取状态 (firecrawl_check_crawl_status)

检查爬取作业的状态。

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

返回：

• 响应包括爬取作业的状态：

8. 提取工具 (firecrawl_extract)

使用 LLM 能力从网页中提取结构化信息。支持云 AI 和自托管 LLM 提取。

最适合：

• 提取特定的结构化数据，如价格、名称、详细信息。

不推荐用于：

• 当你需要页面的全部内容时（请使用 scrape）
• 当你不需要特定的结构化数据时

参数：

• urls: 要从中提取信息的 URL 数组
• prompt: 用于 LLM 提取的自定义提示
• systemPrompt: 用于指导 LLM 的系统提示
• schema: 结构化数据提取的 JSON 模式
• allowExternalLinks: 允许从外部链接提取
• enableWebSearch: 启用网络搜索以获取额外上下文
• includeSubdomains: 在提取中包含子域

当使用自托管实例时，提取将使用您配置的 LLM。对于云 API，它使用 Firecrawl 的托管 LLM 服务。
提示示例：

"从这些产品页面中提取产品名称、价格和描述。"

使用示例：
json
{
"name": "firecrawl_extract",
"arguments": {
"urls": ["https://example.com/page1", "https://example.com/page2"],
"prompt": "提取产品信息，包括名称、价格和描述",
"systemPrompt": "你是一个乐于助人的助手，负责提取产品信息",
"schema": {
"type": "object",
"properties": {
"name": { "type": "string" },
"price": { "type": "number" },
"description": { "type": "string" }
},
"required": ["name", "price"]
},
"allowExternalLinks": false,
"enableWebSearch": false,
"includeSubdomains": false
}
}

返回：

• 根据您的模式定义的提取结构化数据

json
{
"content": [
{
"type": "text",
"text": {
"name": "示例产品",
"price": 99.99,
"description": "这是一个示例产品描述"
}
}
],
"isError": false
}

9. 深度研究工具 (firecrawl_deep_research)

使用智能爬取、搜索和 LLM 分析对查询进行深度网络研究。

最适合：

• 需要多个来源和深入分析的复杂研究问题。

不推荐用于：

• 可以通过单一搜索回答的简单问题
• 当你需要从已知页面获取非常具体的信息时（请使用 scrape）
• 当你需要快速得到结果时（深度研究可能需要时间）

参数：

• query (字符串, 必需): 要探索的研究问题或主题。- maxDepth (number, 可选): 爬取/搜索的最大递归深度（默认：3）。
• timeLimit (number, 可选): 研究会话的时间限制（以秒为单位，默认：120）。
• maxUrls (number, 可选): 要分析的最大URL数量（默认：50）。

提示示例：

"研究电动汽车与汽油车的环境影响。"

使用示例：
json
{
"name": "firecrawl_deep_research",
"arguments": {
"query": "电动汽车与汽油车相比，其环境影响是什么？",
"maxDepth": 3,
"timeLimit": 120,
"maxUrls": 50
}
}

返回：

• 基于研究生成的最终分析。（data.finalAnalysis）
• 也可能包括研究过程中使用的结构化活动和来源。

10. 生成 LLMs.txt 工具 (firecrawl_generate_llmstxt)

为给定的域名生成标准化的 llms.txt 文件（可选地还包括 llms-full.txt）。此文件定义了大型语言模型应如何与该网站交互。

最适合用于：

• 为AI模型创建机器可读的权限指南。

不推荐用于：

• 一般内容提取或研究

参数：

• url (string, 必需): 要分析的网站的基本URL。
• maxUrls (number, 可选): 包含的最大URL数量（默认：10）。
• showFullText (boolean, 可选): 是否在响应中包含llms-full.txt的内容。

提示示例：

"为example.com生成一个LLMs.txt文件。"

使用示例：
json
{
"name": "firecrawl_generate_llmstxt",
"arguments": {
"url": "https://example.com",
"maxUrls": 20,
"showFullText": true
}
}

返回：

• LLMs.txt文件内容（可选地还包括llms-full.txt）

日志系统

服务器包括全面的日志记录：

• 操作状态和进度
• 性能指标
• 积分使用监控
• 速率限制跟踪
• 错误条件

示例日志消息：

[INFO] Firecrawl MCP 服务器初始化成功
[INFO] 正在开始抓取 URL: https://example.com
[INFO] 批处理操作已排队，ID: batch_1
[WARNING] 积分使用已达警告阈值
[ERROR] 超出速率限制，将在2秒后重试...

错误处理

服务器提供强大的错误处理功能：

• 对瞬时错误自动重试
• 带有退避机制的速率限制处理
• 详细的错误信息
• 积分使用警告
• 网络弹性

示例错误响应：

json
{
"content": [
{
"type": "text",
"text": "错误：超出速率限制。将在2秒后重试..."
}
],
"isError": true
}

开发

bash

安装依赖

npm install

构建

npm run build

运行测试

npm test

贡献

1. 分叉仓库
2. 创建你的特性分支
3. 运行测试: npm test
4. 提交拉取请求

感谢贡献者

感谢 @vrknetha, @cawstudios 的初始实现！

感谢MCP.so 和 Klavis AI 提供托管服务，以及@gstarwd, @xiangkaiz 和 @zihaolin96 集成我们的服务器。

许可证

MIT许可证 - 详情请参阅LICENSE文件。