Firecrawl Toolkit

Firecrawl MCP工具包

一款高性能异步MCP服务器，通过Firecrawl API（不包括一些很少使用的接口）提供全面的谷歌搜索和网络内容抓取功能。

该项目建立在 httpx，利用异步客户端和连接池管理为LLM提供稳定高效的外部信息检索工具。

PyPI包

鞭炮工具包：https://pypi.org/project/firecrawl-toolkit/

主要特点

• 异步体系结构：完全基于 asyncio 和 httpx，确保高吞吐量和无阻塞I/O操作。
• HTTP连接池：通过全局管理和重用TCP连接 httpx.AsyncClient 实例，显著提高了高并发下的性能。
• 并发控制：内置全局和每个API端点并发信号量有效管理API请求速率，以防止超过速率限制。
• 自动重试机制：具有指数退避策略的集成请求重试功能可自动处理临时网络波动或服务器错误，增强服务稳定性。
• 智能国家代码解析：包括一个全面的国家名称词典，支持中文、英文、ISO Alpha-2/3和其他格式的输入，并具有自动规范化功能。
• 响应字段映射：搜索/报废响应被标准化为最小的、面向客户端的JSON模式，而不是上游传递有效载荷。
• 废料降噪：内置 excludeTags 选择器过滤删除常见的非内容块（导航、广告、侧边栏、评论等）以提高信号质量。支持返回指定长度的Markdown字符进行截断。
• 灵活的环境变量配置：支持通过环境变量进行微调服务配置。
• 搜索和报废端点执行一些请求预处理和后处理，这可以节省相当多的令牌。

可用工具

此服务提供以下工具：

安装指南

建议使用安装 pip 或 uv.

# Using pip
pip install firecrawl-toolkit

# Or using uv
uv pip install firecrawl-toolkit

快速开始

设置环境变量

创建一个 .env 文件，然后输入您的Firecrawl API密钥：

• STDIO、HTTP和SSE一次只能使用一个。 如果您需要使用多种协议，请为每种协议启动单独的服务。
• 使用多个服务时，请为每个服务指定不同的锁文件。

配置MCP客户端

在MCP客户端配置文件中添加以下服务器配置：

{
  "mcpServers": {
    "firecrawl": {
      "command": "python3",
      "args": ["-m", "firecrawl-toolkit"],
      "env": {
        "FIRECRAWL_API_KEY": ""
      }
    }
  }
}

{
  "mcpServers": {
    "firecrawl": {
      "command": "uvx",
      "args": ["firecrawl-toolkit"],
      "env": {
        "FIRECRAWL_API_KEY": ""
      }
    }
  }
}

刀具参数和使用示例

firecrawl搜索：执行聚合/网络/新闻/图像搜索

参数：

• query （str，必填）：要搜索的关键字。
• country （str，可选）：指定搜索结果的国家/地区。支持中文名称（例如“China”）、英文名称（例如，“United States”）或ISO代码（例如“US”）。默认值为“US”。
• search_num （int，可选）：要返回的结果数，范围为1-100。默认值为20。
• search_time （str，可选）：按时间范围筛选结果。可用值：“小时”、“天”、“周”、“月”、“年”。

例子：

result_json = firecrawl_web_search(
    query="AI advancements 2024",
    country="United States",
    search_num=5,
    search_time="month"
)

响应（已映射）：

• 顶级字段： success, data, creditsUsed
• data.web[]: title, description, url
• data.news[]: title, snippet, url, date
• data.images[]: title, imageUrl, url
• web / news / images 保留数组，可能为空([])
• 缺少的映射字段将保留为 null
• 输出是紧凑的单行JSON（没有额外的空格）

示例响应：

{"success":true,"data":{"web":[{"title":"Example Web","description":"Example description","url":"https://example.com"}],"news":[],"images":[]},"creditsUsed":1}

firecrawl scrape：抓取网页内容

参数：

• url （str，必填）：目标网页的URL。
• excludeTags （list\[str\]，可选，默认 [])：要排除的其他CSS选择器；在归一化和重复数据删除后与内置噪声滤波器选择器合并，除非 emptyTags=True.
• includeTags （list\[str\]，可选，默认 None)：要包含的其他CSS选择器；不应用内置默认值，仅当提供此参数时，才会转发已清理的列表。
• maxCharacters （int，可选，默认 None)：仅截断返回的内容 markdown 前N个字符。无效值（非int， <= 0)被忽略并视为未提供。
• emptyTags （bool，可选，默认 False)：清除此请求的内置排除选择器列表，同时仍保留提供的任何用户 excludeTags.
• headers （dict\[str，str\]，可选，默认 None)：仅当提供非空对象时，根级请求标头才会传递给上游抓取请求。

例子：

result_json = firecrawl_scrape(
    url="https://www.example.com",
    includeTags=["article", ".content"],
    excludeTags=["[class^=\"skip\"]", "[id*=\"disqus\"]"],
    maxCharacters=1200,
    headers={"Authorization": "Bearer token", "X-Trace-Id": "abc123"}
)

这最多返回1200个字符 markdown.

要显式发送空的包含选择器列表，请执行以下操作：

result_json = firecrawl_scrape(
    url="https://www.example.com",
    includeTags=[]
)

要仅禁用一个请求的内置排除选择器，请执行以下操作：

result_json = firecrawl_scrape(
    url="https://www.example.com",
    emptyTags=True
)

要禁用内置的排除选择器但保留自己的选择器，请执行以下操作：

result_json = firecrawl_scrape(
    url="https://www.example.com",
    excludeTags=[".nav"],
    emptyTags=True
)

内置噪音过滤：

• 该工具使用内部 excludeTags 选择器设置为抑制噪声DOM区域并优先考虑主要内容质量。
• includeTags 没有内置默认值，只有在明确提供时才会转发。
• 经过 emptyTags=True 仅清除该请求的内置排除选择器集。
• 如果第一次刮回 data.markdown == ""，该工具自动重试一次，无需 includeTags/excludeTags 作为一种退路。
• maxCharacters 截断在此工具包后处理中本地应用，不会转发到上游Firecrawl有效载荷。

响应（已映射）：

• 顶级字段： success, proxyUsed, title, description, language, markdown, creditsUsed
• markdown 在返回客户端之前对URL进行解码
• 当一个有效 maxCharacters 提供， markdown 长度上限为该值
• 缺少的映射字段将保留为 null
• 输出是紧凑的单行JSON（没有额外的空格）

示例响应：

{"success":true,"proxyUsed":"auto","title":"Example Page","description":"Example summary","language":"en","markdown":"Hello world!","creditsUsed":1}

响应合同注释

• firecrawl-search 和 firecrawl-scrape 成功载荷被映射到稳定的最小模式。
• 缺少的映射字段将保留为 null （数组仍然是数组，可以为空）。
• 成功和错误响应都是简洁的单行JSON。

许可协议

该项目根据MIT许可证获得许可。