firecrawl-mcp

Firecrawl MCPFirecrawl 的模型上下文协议（MCP），提供与 [Fire](https://github.com/mendableai/firecrawl) 结合的网页抓取功能。 > 特别感谢 [@vrknetha](https://github.com/vrknetha)、[@knacklabs](https://www.knacklabs.ai) 提供的初始实现！ ## 功能特点 - 网页抓取、和发现 - 搜索和内容提取 -研究和批量抓- 自动重试和速率限制 - 云和自主托管支持 - SSE 支持 [MCP.so乐场](https://mcpground?firecrawl-mcp-server) 或 [Klav](https://www.klavis.ai/mcp-ser 上试玩我们的 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+ 有关配置 MCP 服务器的最更新说明，请参阅 Cursor 官方文档： [Cursor MCP 服务器配置指南](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers) 要在 Cursor **v0.48.6** 中配置 Firecrawl MCP 1. 打开 Cursor 设置 2. 进入 Features > 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. 进入 Features > 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密钥。如果您还没有密钥，可以在 https://www.firecrawl.dev/app/api-keys 创建帐户并获取。 添加后，刷新 MCP 服务器列表以查看新工具。Composer 代理将在适当时自动使用 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 本地模式运行 使用服务器发送事件（SSE）在本地运行服务器，而不是默认的 stdio 传输： ```bash env SSE_LOCAL=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp ``` 使用网址：http://localhost:3000 ### 通过 Smithery（旧版）安装 通过 [Smithery](https://smithery.ai/server/@mendableai/mcp-server-firecrawl) 自动为 Claude Desktop 安装 Firecrawl： ```bash npx -y @smithery/cli install @mendableai/mcp-server-firecrawl --client claude ``` ### 在 VS Code 上运行 一键安装，请按钮... [](https://insiders.vscode.dev/redirect/mcp=fire&inputs=%5BB%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Firecrawl%20API%2022%2Cpassword%22%true%7DD&config=%722command%22A%22n22%2C%22args%22%%5B%2222%2Cfirecrawl-mcp%22%5D%2C%22env%22%3A%7B%22FIREL_API_KEY%3A%22%24%7Binput%apiKey%7D%7D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=firecrawl&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Firecrawl%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%%22-y%2C%22firecrawl-mcp%22%%2C%22env%22%3A%7B%22FIRECRAWL_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D&quality=insiders) 手动安装时，将以下 JSON 块添加到 VS Code 中的用户设置（JSON）文件中。您可以通过按 `Ctrl + Shift + P` 并输入 `Preferences: Open User Settings (JSON)` 来执行此操作。 ```json { "mcp": { "inputs": [ { "type": "promptString", "id": "apiKey", "description": "Firecrawl API 密钥", "password": true } ], "servers": { "firecrawl": { "command": "npx", "args": ["-y", "firecrawl-mcp"], "env": { "FRAWL_API_KEYinput:apiKey}" } } } } ``` 或者，您可以将其添加到名为 `.vscp.json` 的文件中在工作区中允许您与其他人： ```json { "inputs": { "type": "promptString", "id": "apiKey", "description": "Firecrawl API 密钥", "password": true } ], "servers": { "": { "command": "npx", "args": ["-y", "firecrawl-mcp"], ": { "FIRECRAWL_API_KEY": "${input:api } } } } ``` ## 配置 ### 环境变量 #### 所需 -IRECRAWL_API_KEY`: 您的 Fire 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） ##### 信用使用- `FIREL_CREDIT_WARNING 信用使用警告阈值（默认0） - `FIRECRAWL_CITICAL_THRESHOLD`: 关键阈值（100） 配置示例 对于具有自定义重试和信用监控 API 使用： ```bash # 云 API 所export FIRECRAWL_API_KEY=your-api-key # 可选重试export FIRECRAWL_RETRY_MAX_ATTEMPTS=5 # 增加最大重试次数 CRAWL_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_URLfirecrawl.your-domain.com # 自托管可选身份验证 CRAWL_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":", "FIRECRAWL_RETRY_INITIAL_DELAY": "2000", "FIRECRAWL_RETRY_MAX_DELAY": "300 "FIRECRAWL_RETRY": "3", "FIREC_CREDIT_WARNING_THRESHOLD": "2000", IRECRAWL_CREDIT_CRITICAL_THRESHOLD" } } } } ``` ### 系统配置 服务器包含多个可通过环境变量设置的配置参数。以下是未配置时的默认值： const CONFIG = { retry: { maxAttempts: 3, // 速率限制请求的 initialDelay: 1000, //第一次重试前的初始延迟（毫秒） maxDelay: 10000, // 重试之间的最大延迟（毫秒） backoffFactor: 2, // 指数退避乘数 }, credit: { warningThreshold: 1000, // 信用使用达到此级别时警告 criticalThreshold: 100, // 信用使用达到此级别时严重警告 }, }; ``` 这些配置控制： 1. **重试行为** - 自动重试因速率限制而失败的请求 - 使用指数退避避免淹没 API 使用默认设置，重试将在以下时间尝试 -第一次重试：1 秒延迟 次重试：2 秒延迟 - 第三次重试：4 秒延迟（上限为 maxDelay） 2. **信用使用监控** - 跟 API 使用的信用消耗 - 在指定阈值时提供警告 - 帮助防止意外服务中断 - 示例：使用默认设置： - 剩余 1000 积分时警告 - 剩余 100 积分时严重警告 ### 速率限制和批量处理 服务器利用 Firecrawl 内置的速率限制和批量处理功能： - 自动速率限制处理，带有指数退避 - 批量操作的并行处理 - 智能请求队列和限流 - 暂时错误的自动重试 ## 如何选择工具 使用本指南为您的任务选择合适的工具： - **如果您知道要使用的确切 URL（S）：** - 对于单个 URL：使用 **scrape** - 对于多个 URL：使用 **batch_scrape** - **如果您需要发现网站上的 URL：** 使用 **map** - **如果您要在网络上搜索信息：** 使用 **search **如果您要提取结构化数据：** 使用 **extract** - **如果您要分析整个网站或部分网站：** 使用 **crawl** （有限制！） - **如果您要研究：** 使用 **deep_research** - **如果您要生成 LLMs.txt：** 使用 **generate_llmstxt** ### 快速参考表 | 工具 | 最适合 | 返回类型 | |---------------------|------------------------------------------|-----------------| | | 单个页面内容提取 | markdown/html | | batch_scrape | 多个 的提取 | markdown/html[] | | map | 发现网站上的 URL | URL[] | | crawl | 多页面提取（有限制） | markdown/html[] | | search | 网络搜索信息 | results[] | | extract | 页面结构化数据 | JSON | | deep_research | 深入的多源研究 | summary, sources| | generate_llmstxt | 域的 LLMs.txt | text | ## 可用工具 ### 1. Scrape 工具 (`firecrawl_scrape`) 使用高级选项抓取单个 URL 的内容。 **最适合：** - 单个页面内容提取，当您确切知道要提取哪个页面。 **不推荐用于：** - 提取多个页面的使用 batch_scrape 获取已知 URL，或使用 map + batch_scrape 发现 URL，或使用 crawl 获取完整页面内容） - 当您不确定哪个页面包含信息（使用 search） - 当您需要结构化数据（使用 extract） **常见错误：** - 使用 scrape 获取 URL 列表（改为使用 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": "firec_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. Map 工具 (`firecrawl_map`) 映射网站以发现站点上所有索引的 URL。 **最适合：** - 在决定要抓取什么之前发现网站上的 URL - 查找网站的特定部分 **不推荐用于：** - 当您已经知道要使用的特定 URL（使用 scrape 或 batch_scrape） - 当您需要页面的内容（在映射后使用 scrape） **常见错误：** - 使用 crawl 来发现 URL 而不是 map **提示示例：** > "列出 example.com 上的所有 URL。" **用法示例：** ```json { "name": "firecrawl_map", "arguments": { "url": "https://example.com" } } ``` **返回：** - 站点上找到的 URL 数组 ### 4. 搜索工具 (`firecrawl_search`) 搜索网络并可选地从搜索结果中提取内容。 **最适合：** - 跨多个网站查找特定信息，当您不知道哪个网站有该信息时。 - 当您需要查询的最相关内容时 **不推荐用于：** - 当您已经知道要抓取哪个网站（使用 scrape） - 当您需要对单个网站进行全面覆盖（使用 map 或 crawl） **常见错误：** - 对于开放式问题，使用 crawl 或 map（改为使用 search） **用法示例：** ```json { "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 的前两层获取所有博客文章。" **用法示例：** ```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） - 当您需要快速获得结果时（深度研究可能需要时间） **参数：** - 查询（字符串，必填）：要探索的研究问题或主题。 - maxDepth（数字，可选）：爬取/搜索的最大递归深度（默认值：3）。 - timeLimit（数字，可选）：研究会话的时间限制（秒）（默认值：120）。 - maxUrls（数字，可选）：要分析的最大URL数量（默认值：50）。 **提示示例：** > "研究电动汽车与汽油汽车相比的环境影响。" **用法示例：** ```json { "name": "firecrawl_deep_research", "arguments": { "query": "电动汽车与汽油汽车相比的环境影响是什么？", "maxDepth": 3, "timeLimit": 120, "maxUrls": 50 } } ``` **返回：** - 基于研究的LLM生成的最终分析。（data.finalAnalysis） - 还可能包括研究过程中使用的结构化活动和来源。 ### 10. 生成LLMs.txt工具（`firecrawl_generate_llmstxt`） 为给定域名生成标准化的llms.txt（和可选的llms-full.txt）文件。该文件定义了大型语言模型如何与站点交互。 **最适合：** - 为AI模型创建机器可读的权限指南。 **不推荐：** - 一般内容提取或研究 **参数：** - url（字符串，必填）：要分析的网站的基本URL。 - maxUrls（数字，可选）：要包含的最大URL数量（默认值：10）。 - showFullText（布尔值，可选）：是否在响应中包含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](https://github.com/vrknetha)、[@cawstudios](https://caw.tech) 提供的初始实现！ 感谢 MCP.so 和 Klavis AI 提供托管服务，以及 [@gstarwd](https://github.com/gstarwd)、[@xiangkaiz](https://github.com/xiangkaiz) 和 [@zihaolin96](https://github.com/zihaolin96) 集成我们的服务器。 ## 许可证 MIT 许可证 - 参见 LICENSE 文件了解详情