Firecrawl MCP 服务器

一个与 Firecrawl 集成的模型上下文协议 (MCP) 服务器实现，用于网络爬取功能。

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

特性

• 网络爬取、抓取和发现
• 搜索与内容提取
• 深度研究与批量爬取
• 带有代理浏览器自动化的云端浏览器会话
• 自动重试与速率限制
• 云服务与自托管支持
• SSE 支持

您可以在 MCP.so 的 Playground 或 Klavis AI 上体验我们的 MCP 服务器。

安装

使用 npx 运行

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

手动安装

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. 输入以下代码：

   {
     "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”（或您喜欢的名称）
   • 类型：“命令”
   • 命令：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 代理会在适当的时候自动使用 Firecrawl MCP，但您也可以通过描述您的网页抓取需求来明确请求它。通过 Command+L（Mac）打开 Composer，选择提交按钮旁边的“代理”，然后输入您的查询。

在 Windsurf 中运行

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

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

使用可流式 HTTP 本地模式运行

要使用可流式 HTTP 在本地运行服务器，而不是默认的 stdio 传输方式：

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

使用 URL：http://localhost:3000/mcp

通过 Smithery 安装（旧版）

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

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)”来完成此操作。

{
  "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 文件中。这样就可以与他人共享配置：

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

# 云 API 所需
export FIRECRAWL_API_KEY=您的 API 密钥

# 可选的重试配置
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 时触发严重警报

对于自托管实例：

# 自托管所需
export FIRECRAWL_API_URL=https://firecrawl.您的域名.com

# 自托管的可选认证
export FIRECRAWL_API_KEY=您的 API 密钥  # 如果您的实例需要认证

# 自定义重试配置
export FIRECRAWL_RETRY_MAX_ATTEMPTS=10
export FIRECRAWL_RETRY_INITIAL_DELAY=500     # 从更快的延迟开始重试

与 Claude Desktop 的使用

将以下内容添加到 claude_desktop_config.json 中：

{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "您的 API 密钥",

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

系统配置

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

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

这些配置控制：

1. 重试行为

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

2. 信用使用监控

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

速率限制与批处理

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

• 自动处理速率限制并采用指数退避
• 高效的并行处理用于批处理操作
• 智能请求排队和节流
• 自动重试临时性错误

如何选择工具

请使用本指南来为您的任务选择合适的工具：

• 如果您知道确切的目标 URL：
  • 单个 URL：使用 scrape（推荐 JSON 格式以获取结构化数据）
  • 多个 URL：使用 batch_scrape
• 如果您需要发现网站上的 URL： 使用 map
• 如果您想在网络上搜索信息： 使用 search
• 如果您需要跨多个未知来源进行复杂研究： 使用 agent
• 如果您需要分析整个网站或部分页面： 使用 crawl（请注意限制！）
• 如果您需要交互式的浏览器自动化操作（点击、输入、导航）：使用 scrape + interact
• 如果您需要原始的 CDP 浏览器会话（高级用法）：使用 browser（已弃用）

快速参考表

工具	最适合场景	返回结果
scrape	提取单个页面内容	JSON（推荐）或 Markdown
interact	与已抓取的页面进行交互	执行结果
batch_scrape	提取多个已知 URL 的内容	JSON（推荐）或 Markdown[]
map	发现网站上的 URL	URL[]
crawl	多页内容提取（有限制）	Markdown/HTML[]
search	在网络上搜索信息	搜索结果[]
agent	复杂的多源研究	JSON（结构化数据）
browser	交互式多步骤自动化（已弃用）	包含实时浏览器的会话

格式选择指南

在使用 scrape 或 batch_scrape 时，请选择合适的格式：

• JSON 格式（大多数情况下推荐）： 当您需要从页面中提取特定数据时使用。根据所需内容定义模式，这样可以保持响应较小，并避免上下文窗口溢出。
• Markdown 格式（谨慎使用）： 仅在确实需要完整页面内容时使用，例如阅读整篇文章以进行摘要或分析页面结构。

1. 抓取工具（firecrawl_scrape）

从单个 URL 抓取内容，并提供高级选项。

最适合：

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

不建议用于：

• 从多个页面提取内容（对于已知 URL，请使用 batch_scrape；若需先发现 URL，则可结合 map 和 batch_scrape；如需完整页面内容，可使用 crawl）
• 当不确定哪一页包含所需信息时（请使用 search）。

常见错误：

• 将 scrape 用于 URL 列表（应改用 batch_scrape）。
• 默认使用 Markdown 格式（应使用 JSON 格式以仅提取所需内容）。

选择合适的格式：

• JSON 格式（推荐）： 对于大多数场景，建议使用带有 Schema 的 JSON 格式来提取特定数据。这样可以确保响应聚焦，避免上下文窗口溢出。
• Markdown 格式： 仅在任务确实需要完整页面内容时使用（例如，总结整篇文章或分析页面结构）。

提示示例：

“从 https://example.com/product 获取产品详情。”

使用示例（JSON 格式——推荐）：

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/product",
    "formats": [{
      "type": "json",
      "prompt": "提取产品信息",
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "price": { "type": "number" },
          "description": { "type": "string" }
        },
        "required": ["name", "price"]
      }
    }]
  }
}

使用示例（Markdown 格式——当需要完整内容时）：

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

使用示例（品牌化格式——提取品牌标识）：

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

品牌化格式： 提取全面的品牌标识（颜色、字体、排版、间距、Logo、UI 组件等），用于设计分析或样式复刻。

返回值：

• 按指定格式返回 JSON 结构化数据、Markdown 内容、品牌档案或其他格式。

2. 批量抓取工具（firecrawl_batch_scrape）

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

最适合：

• 从多个页面获取内容，且你确切知道要抓取哪些页面时。

不建议用于：

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

常见错误：

• 一次性使用 batch_scrape 抓取过多 URL（可能导致速率限制或令牌溢出）。

提示示例：

“获取以下三篇博客文章的内容：[url1, url2, url3]。”

使用示例：

{
  "name": "firecrawl_batch_scrape",
  "arguments": {
    "urls": ["https://example1.com", "https://example2.com"],
    "options": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}

返回值：

• 响应包含操作 ID，用于检查状态：

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

3. 检查批量状态（firecrawl_check_batch_status）

检查批量操作的状态。

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

4. 网站映射工具（firecrawl_map）

映射一个网站，以发现该站点上所有已索引的 URL。

最适合：

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

不建议用于：

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

常见错误：

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

提示示例：

“列出 example.com 上的所有 URL。”

使用示例：

{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com"
  }
}

返回值：

• 该站点上找到的 URL 数组。

5. 搜索工具（firecrawl_search）

在网络上进行搜索，并可选择性地从搜索结果中提取内容。

最适合：

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

不建议用于：

• 当你已经知道要抓取哪个网站时（请使用 scrape）。
• 当你需要对单个网站进行全面覆盖时（请使用 map 或 crawl）。

常见错误：

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

使用示例：

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "2023 年最新的 AI 研究论文",
    "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 前两层的所有博客文章。”

使用示例：

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

返回值：

• 响应包含操作 ID，用于检查状态：

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

7. 检查爬取状态（firecrawl_check_crawl_status）

检查爬取作业的状态。

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

返回值：

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

8. 提取工具 (firecrawl_extract)

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

最适合：

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

不推荐用于：

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

参数：

• urls: 需要提取信息的URL数组
• prompt: 用于大模型提取的自定义提示词
• systemPrompt: 引导大模型的系统提示词
• schema: 用于结构化数据提取的JSON模式
• allowExternalLinks: 是否允许从外部链接提取
• enableWebSearch: 是否启用网络搜索以获取更多上下文
• includeSubdomains: 是否包含子域名的提取

当使用自托管实例时，提取将使用您配置的大模型。对于云API，则会使用Firecrawl的托管大模型服务。 提示词示例：

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

使用示例：

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

返回结果：

• 按照您的模式定义的提取出的结构化数据

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

9. 代理工具 (firecrawl_agent)

自主网络研究代理。这是一个独立的AI代理层，能够根据您的查询独立浏览互联网、搜索信息、导航页面并提取结构化数据。

工作原理：

代理会自动执行网络搜索、跟随链接、读取页面并收集数据。此过程是异步的——它会立即返回一个作业ID，您可以轮询firecrawl_agent_status来检查完成状态并获取结果。

异步工作流程：

1. 使用您的提示词/模式调用firecrawl_agent → 返回作业ID
2. 在代理进行研究的同时，您可以处理其他任务（复杂查询可能需要几分钟）
3. 使用作业ID轮询firecrawl_agent_status以查看进度
4. 当状态为“已完成”时，响应中将包含提取的数据

最适合：

• 复杂的研究任务，且您不知道确切的URL
• 多源数据收集
• 寻找分散在全网的信息
• 您可以在等待结果的同时进行其他工作的任务

不推荐用于：

• 简单的单页抓取，且您已知URL（请使用带有JSON格式的scrape——更快更便宜）

参数：

• prompt: 您想要的数据的自然语言描述（必填，最多10,000字符）
• urls: 可选的URL数组，用于让代理专注于特定页面
• schema: 可选的结构化输出JSON模式

提示词示例：

“找出Firecrawl的创始人及其背景”

使用示例（启动代理后轮询结果）：

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "找出2024年成立的前5家AI初创公司及其融资金额",
    "schema": {
      "type": "object",
      "properties": {
        "startups": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "funding": { "type": "string" },
              "founded": { "type": "string" }
            }
          }
        }
      }
    }
  }
}

然后使用返回的作业ID轮询firecrawl_agent_status。

使用示例（带URL——代理专注于特定页面）：

{
  "name": "firecrawl_agent",
  "arguments": {
    "urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    "prompt": "比较这些页面的功能和定价信息"
  }
}

返回结果：

• 用于检查状态的作业ID。使用firecrawl_agent_status轮询以获取结果。

10. 检查代理状态 (firecrawl_agent_status)

检查代理作业的状态，并在完成后获取结果。在启动代理后，使用此接口轮询结果。

轮询模式： 对于复杂查询，代理研究可能需要几分钟。请定期（例如每10-30秒）轮询此端点，直到状态变为“已完成”或“失败”。

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

可能的状态：

• processing: 代理仍在研究中——稍后再试
• completed: 研究已完成——响应中包含提取的数据
• failed: 发生了错误

11. 浏览器创建 (firecrawl_browser_create) — 已弃用

已弃用： 建议改用firecrawl_scrape + firecrawl_interact。Interact允许您先抓取页面，然后再点击、填写表单并导航，而无需手动管理会话。

创建用于交互式自动化的云端浏览器会话。

参数：

• ttl: 会话总生命周期，单位为秒（30-3600，可选）
• activityTtl: 空闲超时时间，单位为秒（10-3600，可选）
• streamWebView: 是否启用实时视图流（可选）
• profile: 保存并跨会话重复使用浏览器状态（可选）
  • name: 配置文件名称（同名会话共享状态）
  • saveChanges: 是否将更改保存回配置文件（默认：是）

使用示例：

{
  "name": "firecrawl_browser_create",
  "arguments": {
    "ttl": 600,
    "profile": { "name": "my-profile", "saveChanges": true }
  }
}

返回结果：

• 会话ID、CDP URL以及实时视图URL

12. 浏览器执行（firecrawl_browser_execute）—— 已弃用

已弃用：建议改用 firecrawl_scrape + firecrawl_interact。

在浏览器会话中执行代码。支持 agent-browser 命令（bash）、Python 或 JavaScript。

推荐：使用带有 agent-browser 命令的 bash（每个沙盒中均已预装）：

{
  "name": "firecrawl_browser_execute",
  "arguments": {
    "sessionId": "session-id-here",
    "code": "agent-browser open https://example.com",
    "language": "bash"
  }
}

常见的 agent-browser 命令：

命令	描述
agent-browser open <url>	导航到指定 URL
agent-browser snapshot	包含可点击引用的无障碍树
agent-browser click @e5	根据快照中的引用点击元素
agent-browser type @e3 "text"	在元素中输入文本
agent-browser get title	获取页面标题
agent-browser screenshot	截取屏幕截图
agent-browser --help	完整命令参考

对于 Playwright 脚本，使用 Python：

{
  "name": "firecrawl_browser_execute",
  "arguments": {
    "sessionId": "session-id-here",
    "code": "await page.goto('https://example.com')\ntitle = await page.title()\nprint(title)",
    "language": "python"
  }
}

13. 浏览器列表（firecrawl_browser_list）—— 已弃用

已弃用：建议改用 firecrawl_scrape + firecrawl_interact。

列出浏览器会话，可选择按状态过滤。

{
  "name": "firecrawl_browser_list",
  "arguments": {
    "status": "active"
  }
}

14. 浏览器删除（firecrawl_browser_delete）—— 已弃用

已弃用：建议改用 firecrawl_scrape + firecrawl_interact。

销毁一个浏览器会话。

{
  "name": "firecrawl_browser_delete",
  "arguments": {
    "sessionId": "session-id-here"
  }
}

日志系统

服务器包含全面的日志记录功能：

• 操作状态和进度
• 性能指标
• 信用使用监控
• 速率限制跟踪
• 错误情况

日志示例：

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

错误处理

服务器提供强大的错误处理机制：

• 自动重试临时性错误
• 具有退避策略的速率限制处理
• 详细的错误信息
• 信用使用警告
• 网络韧性

错误响应示例：

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

开发

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

贡献

1. 分支仓库
2. 创建你的功能分支
3. 运行测试：npm test
4. 提交拉取请求

感谢贡献者

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

同时感谢 MCP.so 和 Klavis AI 的托管支持，以及 @gstarwd、@xiangkaiz 和 @zihaolin96 对我们服务器的集成工作。

许可证

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

Firecrawl MCP Server 快速上手指南

Firecrawl MCP Server 是一个基于模型上下文协议（MCP）的服务端实现，集成了 Firecrawl 强大的网页抓取、爬取和内容提取能力，可让 AI 助手直接操作网络数据。

环境准备

• 系统要求：支持 macOS、Linux 或 Windows。
• 前置依赖：
  • 已安装 Node.js (建议 v18 或更高版本)。
  • 已安装 npm 或 npx (通常随 Node.js 一同安装)。
• API 密钥：
  • 访问 Firecrawl 官网 注册账号并获取 FIRECRAWL_API_KEY。
  • 若使用自托管实例，需准备 FIRECRAWL_API_URL。

安装步骤

方式一：通过 npx 直接运行（推荐测试用）

无需全局安装，直接在终端运行以下命令（替换为你的 API Key）：

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

Windows 用户注意：若上述命令报错，请尝试使用 cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"。

方式二：全局安装

npm install -g firecrawl-mcp

安装完成后，可通过配置环境变量运行：

export FIRECRAWL_API_KEY=fc-YOUR_API_KEY
firecrawl-mcp

集成到主流 IDE/编辑器

1. Cursor (v0.45.6+)

1. 打开 Cursor 设置 (Settings)。
2. 进入 Features > MCP Servers。
3. 点击 + Add new global MCP server。
4. 填入以下配置（请将 YOUR-API-KEY 替换为实际密钥）：

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR-API-KEY"
      }
    }
  }
}

2. VS Code

1. 按下 Ctrl + Shift + P (Mac: Cmd + Shift + P)，输入 Preferences: Open User Settings (JSON) 并打开。
2. 在配置文件中添加以下内容：

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

保存后，VS Code 会在首次使用时提示你输入 API Key。

3. Claude Desktop

编辑 claude_desktop_config.json 文件，添加：

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

基本使用

配置完成后，重启你的 AI 编辑器或客户端。在对话框中（如 Cursor 的 Composer 模式），你可以直接使用自然语言描述需求，AI 将自动调用 Firecrawl 工具。

常用场景示例

• 抓取单个页面内容

  “请抓取 https://example.com 的主要内容，并以 JSON 格式返回标题和正文。”

  • 底层工具：scrape

• 发现网站内的所有链接

  “帮我找出 https://example.com 站点下的所有子页面链接。”

  • 底层工具：map

• 批量抓取多个已知 URL

  “请同时抓取以下三个网址的内容：[url1, url2, url3]。”

  • 底层工具：batch_scrape

• 全网搜索特定信息

  “搜索关于 'AI 最新进展' 的网络信息，并总结前三条结果。”

  • 底层工具：search

• 深度研究与多源分析

  “调研一下竞争对手 X 的产品定价策略，需要综合多个来源的信息。”

  • 底层工具：agent

工具选择速查

你的需求	推荐工具
获取单个页面数据	scrape
获取多个指定页面数据	batch_scrape
寻找站点内的所有链接	map
搜索引擎查找信息	search
复杂的多源深度研究	agent
全站爬取（需限制范围）	crawl
模拟浏览器交互（点击/输入）	scrape + interact

高级配置（可选）

如需调整重试机制或监控用量，可在启动命令前添加环境变量：

# 示例：增加重试次数和调整信用额度警告阈值
env FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
    FIRECRAWL_RETRY_MAX_ATTEMPTS=5 \
    FIRECRAWL_CREDIT_WARNING_THRESHOLD=2000 \
    npx -y firecrawl-mcp