使用说明

Firecrawl工具包

将网页和PDF转换为本地可搜索的代理Markdown。

Firecrawl工具包是建立在Firecrawlneneneba API之上的第一个CLI网络捕获工具。它专为基于shell的代理而设计，如Codex、Claude Code、OpenCode和其他本地自动化工作流。

CLI不会将长网页转储到模型上下文中，而是将页面保存为本地Markdown文件，并仅向stdout打印最小的成功/失败信号。

firecrawl scrape --url "https://example.com/article" --output article --path ./Temp-Scrape
# true

然后让您的代理使用正常的本地工具检查文件：

rg -n "pricing|risk|governance|download|PDF" ./Temp-Scrape
bat --paging=never --line-range 40:120 ./Temp-Scrape/article.md

刮一次。在本地搜索。保持上下文干净。

为什么存在此工具包

大多数网络搜索或抓取工具将网页视为即时的模型输入。这适用于短页面，但对于长报告、新闻文章、PDF、文档页面和研究材料，它很快就会崩溃。

此工具包使用不同的工作流程：

remote URL / PDF
→ local Markdown file
→ rg / bat / sed / awk / local file tools
→ agent reads only the relevant sections

当代理需要收集多个来源、比较报告、检查引用或构建本地研究文件夹时，这尤其有用。

目标不是生产完全干净的纯物品提取物。目标是生产 完整、可搜索、代理人可读的本地源材料 具有减少的网络噪声和最小的上下文污染。

核心工作流程

1.将网页或PDF抓取到本地Markdown中

firecrawl scrape \
  --url "https://example.com/report-or-article" \
  --output report \
  --path ./Temp-Scrape

关于成功：

true

文件另存为：

./Temp-Scrape/report.md

生成的Markdown以源元数据开头：

## title:
## description:
## url:
## language:
## creditsUsed:

markdown content

2.本地搜索

rg -n "agentic|governance|pricing|risk|EBIT|download" ./Temp-Scrape

3.只读相关章节

bat --paging=never --line-range 80:150 ./Temp-Scrape/report.md

或者使用标准的Unix工具：

sed -n '80,150p' ./Temp-Scrape/report.md

为什么stdout故意小

用于文件生成命令，例如 scrape，stdout故意最小化。

关于成功：

true

失败时：

false
<short error reason>

默认情况下，大页面内容会写入磁盘，而不会打印到stdout。这是有意的：代理不应该意外地将50k、100k或500k字符的页面摄入上下文中。

推荐的模式是：

scrape to file
→ inspect file size / headings / keywords
→ read only the useful ranges

内置样板过滤

默认情况下，scratch命令应用内置的噪波过滤器。

它减少了常见的非内容区域，例如：

脚本、样式、表单、输入、按钮
导航栏、页眉、页脚、侧边栏
菜单和导航块
标志和品牌块
可访问性跳过链接和视觉隐藏元素
广告和广告容器
侧边栏
面包屑和分页
相关、推荐和趋势部分
常见布局偏移/模块块

这并不意味着要积极删除所有非文章元素。优先事项是 低噪音的高召回率：在删除明显样板的同时，保持源材料对本地搜索有用。

使用 --scroll 当页面在提取之前需要短暂的等待和正文滚动时，延迟加载的内容就有机会出现。

如果页面在不寻常的区域包含有用内容，您可以禁用内置过滤器：

firecrawl scrape \
  --url "https://example.com/page" \
  --output page-raw \
  --empty-tags

您还可以添加自己的排除项：

firecrawl scrape \
  --url "https://example.com/page" \
  --output page \
  --exclude-tags ".newsletter,.promo,aside.related"

安装

Python包

Python包提供了MCP服务器。

uvx firecrawl-toolkit

包裹：

firecrawl-toolkit

Go CLI

独立CLI位于 cli 目录。

从源代码构建：

cd cli
go test ./...
go build -o firecrawl .

运行：

./firecrawl --help

构建Windows示例：

cd cli
go build -o firecrawl.exe .

API 密钥

Go CLI从以下位置读取Firecrawl API密钥：

FIRECRAWL_KEY

Linux/macOS：

export FIRECRAWL_KEY="fc-..."

Windows PowerShell：

$env:FIRECRAWL_KEY="fc-..."

Python MCP服务器使用：

FIRECRAWL_API_KEY

API基本URL

默认情况下，Go CLI和Python MCP服务器都使用官方的Firecrawl API基础URL：

https://api.firecrawl.dev/v2

对于自托管的Firecrawl兼容服务，请设置：

FIRECRAWL_BASE_URL

Linux/macOS：

export FIRECRAWL_BASE_URL="https://your-firecrawl.example/v2"

Windows PowerShell：

$env:FIRECRAWL_BASE_URL="https://your-firecrawl.example/v2"

CLI命令

firecrawl aggregated
firecrawl web
firecrawl news
firecrawl image
firecrawl scholar
firecrawl scrape
firecrawl parse
firecrawl audio-scrape
firecrawl video-scrape
firecrawl credit-usage

常见CLI选项

`--proxy`

可选。指向Firecrawl API的CLI请求的代理URL。支持的方案有 http, https, socks4, socks4a, socks5，以及 socks5h.

使用URL userinfo进行代理身份验证，或省略它进行无身份验证：

firecrawl web --query "AI policy" --proxy "http://user:pass@127.0.0.1:8080"
firecrawl scrape --url "https://example.com" --output example --proxy "socks5://127.0.0.1:1080"

报废命令

基本用途

firecrawl scrape \
  --url "https://example.com/article" \
  --output article

文中写道：

article.md

保存到目录中

firecrawl scrape \
  --url "https://example.com/article" \
  --output article \
  --path ./Temp-Scrape

文中写道：

./Temp-Scrape/article.md

如果目录不存在，CLI会尝试创建它。

剪贴PDF

firecrawl scrape \
  --url "https://example.com/report.pdf" \
  --output report-pdf \
  --path ./Temp-Scrape

CLI请求Markdown输出并启用Firecrawl的PDF解析器。

报废选项

`--output`

必修的。导出名称。

firecrawl scrape --url "https://example.com" --output example

CLI写道：

example.md

如果提供的名称已以结尾 .md，它被保存了下来。

`--path`

可选。输出目录。

firecrawl scrape --url "https://example.com" --output example --path ./exports

`--url`

必修的。目标网页或PDF URL。

firecrawl scrape --url "https://example.com" --output example

`--include-tags`

可选。要包含的CSS选择器。

当您知道有用内容在特定区域内时，请使用此选项：

firecrawl scrape \
  --url "https://example.com" \
  --output page \
  --include-tags "article"

多个选择器：

firecrawl scrape \
  --url "https://example.com" \
  --output page \
  --include-tags ".article-body,#content,main"

当选择器包含空格、引号或逗号时，建议使用JSON数组形式：

firecrawl scrape \
  --url "https://example.com" \
  --output page \
  --include-tags '["main article",".post-content","#content"]'

`--exclude-tags`

可选。要排除的其他CSS选择器。

firecrawl scrape \
  --url "https://example.com" \
  --output page \
  --exclude-tags ".nav,.footer,#sidebar"

这将与内置的样板过滤器合并。

`--empty-tags`

可选。禁用此请求的内置排除选择器列表。

firecrawl scrape \
  --url "https://example.com" \
  --output page-raw \
  --empty-tags

用户提供 --exclude-tags 仍然适用：

firecrawl scrape \
  --url "https://example.com" \
  --output page-custom \
  --empty-tags \
  --exclude-tags ".nav"

`--scroll`

可选。在抓取之前启用等待和滚动操作。

启用后，scratch会在请求负载中发送以下操作：

[
  {
    "type": "wait",
    "milliseconds": 2
  },
  {
    "type": "scroll",
    "direction": "down",
    "selector": "body"
  }
]

使用 --scroll 当页面需要额外的交互时：

firecrawl scrape \
  --url "https://example.com" \
  --output page \
  --scroll

`--skip-tls`

可选。跳过上游抓取目标的TLS证书验证。

默认情况下，启用TLS证书验证。

firecrawl scrape \
  --url "https://example.com" \
  --output page \
  --skip-tls

`--headers`

可选。请求头的JSON对象。

firecrawl scrape \
  --url "https://example.com" \
  --output page \
  --headers '{"X-Trace-Id":"abc123"}'

`--headers-file`

可选。头文件的路径。文件被自动检测为以下标准格式之一：

JSON标头或Cookie， headers/cookies 数组或浏览器扩展cookie导出数组
HTTP标头字符串，例如浏览器样式 Name: value 线条
Netscape cookie文件
Cookie标头值，例如 a=1; b=2

firecrawl scrape \
  --url "https://example.com" \
  --output page \
  --headers-file ./headers.txt

小心使用敏感的标题。除非您了解风险，否则避免传递凭据、Cookie或授权令牌。

`--timeout`

可选。请求超时（秒）。默认值为 120.

firecrawl scrape \
  --url "https://example.com" \
  --output page \
  --timeout 180

`--proxy`

可选。从CLI到Firecrawl API的请求的代理URL。支持 http, https, socks4, socks4a, socks5，以及 socks5h，具有URL用户信息身份验证或无身份验证。

学者指挥

scholar 搜索研究论文并将紧凑的单行JSON打印到stdout。

firecrawl scholar \
  --query "AI" \
  --search-num 3 \
  --categories "cs.CY" \
  --time-from "2000-05-28" \
  --time-to "2026-06-28"

该命令向发送GET请求 /v2/search/research/papers 具有查询字符串参数和包含以下内容的JSON正文 timeout.

学者选择

`--query`

必修的。研究论文搜索关键字。最小长度为 1.

`--search-num`

可选。要返回的纸张数量。法律范围为 1 到 500默认值为 5.

`--categories`

可选。逗号分隔的纸张类别过滤器。所有过滤器必须匹配。

`--time-from`

可选。包括创建/更新日期的下限。格式： yyyy-MM-dd例如 2000-05-28.

`--time-to`

可选。包括创建/更新日期的上限。格式： yyyy-MM-dd例如 2026-06-28.

`--timeout`

可选。请求超时（秒）。默认值为 120.

`--proxy`

可选。从CLI到Firecrawl API的请求的代理URL。支持 http, https, socks4, socks4a, socks5，以及 socks5h.

输出字段：

{"data":{"scholar":[{"abstract":"Paper abstract","paperId":"2581735124241874","primaryId":"arxiv:2307.10057","score":0.956892745058914,"title":"Paper title"}]},"success":true}

解析命令

使用 parse 对于来自URL或本地文件的文档。该命令将Markdown写入本地 .md 仅用于文件和打印 true 或 false 到stdout。

解析文档URL

firecrawl parse \
  --url "https://example.com/report.xlsx" \
  --output report \
  --path ./Temp-Scrape

URL模式通过抓取端点发送文档URL，输出Markdown，支持PDF解析器，保留base64图像，并配置超时。

解析本地文件

firecrawl parse \
  --file ./report.xlsx \
  --output report \
  --path ./Temp-Scrape

文件模式将本地文件与多部分表单数据一起上传到解析端点。

支持的本地文件扩展名：

.html .htm .pdf .docx .doc .odt .rtf .xlsx .xls

解析选项

`--url`

目标文档URL。除非满足以下条件，否则为必填项 --file 提供。 --url 和 --file 是相互排斥的。

firecrawl parse --url "https://example.com/report.pdf" --output report

`--file`

本地文档文件。除非满足以下条件，否则必须 --url 提供。

firecrawl parse --file ./report.pdf --output report

`--output`

必修的。导出名称。结果另存为 <output>.md.

`--path`

`--skip-tls`

可选。仅URL模式。跳过上游文档URL的TLS证书验证。默认值为false。

`--timeout`

可选。请求超时（秒）。默认值为 120.

`--proxy`

可选。从CLI到Firecrawl API的请求的代理URL。支持 http, https, socks4, socks4a, socks5，以及 socks5h.

生成的Markdown以以下内容开头：

## title:
## url:
## language:
## creditsUsed:

markdown content

音频和视频抓取命令

audio-scrape 和 video-scrape 请求Firecrawl AV提取并将紧凑的单行JSON打印到stdout。

音频刮擦

firecrawl audio-scrape \
  --url "https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  --timeout 60

输出字段：

{"creditsUsed":5,"title":"Video title","description":"Video description","audio":"https://storage.example/audio.mp3","success":true}

视频抓取

firecrawl video-scrape \
  --url "https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  --timeout 60

输出字段：

{"creditsUsed":5,"title":"Video title","description":"Video description","video":"https://storage.example/video.mp4","success":true}

这两个命令都需要 --url. --timeout 可选，接受秒，默认为 120，并以毫秒为单位转发到Firecrawl。 --proxy 还支持对Firecrawl API的CLI请求。

搜索命令

搜索命令返回紧凑的单行JSON。

firecrawl aggregated --query "AI governance 2026" --country US --search-num 10
firecrawl web        --query "AI governance 2026" --country US --search-num 10
firecrawl news       --query "OpenAI news" --search-time week
firecrawl image      --query "firecrawl logo" --search-num 10

可用搜索命令：

aggregated  web + news + images
web         web results
news        news results
image       image results

搜索选项

`--query`

必修的。搜索关键字。

firecrawl web --query "AI pricing SaaS"

`--country`

可选。国家或地区名称/ISO代码。默认值为 US.

firecrawl web --query "AI policy" --country "United States"
firecrawl web --query "AI policy" --country US

`--search-num`

可选。结果数量，来自 1 到 100默认值为 20.

firecrawl web --query "AI policy" --search-num 5

`--search-time`

可选。时间过滤器。

允许值：

hour
day
week
month
year

例子：

firecrawl news --query "AI regulation" --search-time week

`--timeout`

可选。请求超时（秒）。默认值为 120.

`--proxy`

可选。从CLI到Firecrawl API的请求的代理URL。支持 http, https, socks4, socks4a, socks5，以及 socks5h.

搜索输出

搜索命令输出紧凑的JSON：

{"success":true,"data":{"web":[],"news":[],"images":[]},"creditsUsed":1}

映射字段：

data.web[]:
  title
  description
  url

data.news[]:
  title
  snippet
  url
  date

data.images[]:
  title
  imageUrl
  url

搜索结果旨在帮助代理发现URL。如需详细阅读，请将选定的URL抓取到本地Markdown文件中。

推荐模式：

firecrawl web --query "AI trust maturity survey 2026" --search-num 5
firecrawl scrape --url "<selected-url>" --output ai-trust-survey --path ./Temp-Scrape
rg -n "governance|risk|agentic|maturity" ./Temp-Scrape

信贷使用

检查Firecrawl团队信用使用情况：

firecrawl credit-usage

漂亮的印刷：

firecrawl credit-usage --pretty

credit-usage 还支持 --proxy 用于向Firecrawl API发出CLI请求。

默认输出为JSON：

{"success":true,"data":{"remainingCredits":1000,"planCredits":500000,"billingPeriodStart":"2025-01-01T00:00:00Z","billingPeriodEnd":"2025-01-31T23:59:59Z"}}

退出行为

刮擦和解析

成功：

true

失败：

false
<error reason>

CLI仅在成功抓取或解析后写入Markdown文件。失败时不会创建或覆盖现有文件。

搜索、学者、信用使用、音频抓取和视频抓取

搜索， scholar、信用使用， audio-scrape，以及 video-scrape 命令输出JSON。

示例：本地研究文件夹

mkdir -p ./Temp-Scrape

firecrawl scrape \
  --url "https://www.mckinsey.com/capabilities/tech-and-ai/our-insights/tech-forward/state-of-ai-trust-in-2026-shifting-to-the-agentic-era" \
  --output mckinsey-ai-trust-2026 \
  --path ./Temp-Scrape

firecrawl scrape \
  --url "https://www.reuters.com/business/world-at-work/ai-will-lead-labour-shortages-jeff-bezos-says-vivatech-2026-06-17/" \
  --output reuters-bezos-ai-labor \
  --path ./Temp-Scrape

rg -n "agentic|governance|risk|labor shortage|AI" ./Temp-Scrape
bat --paging=never --line-range 1:120 ./Temp-Scrape/mckinsey-ai-trust-2026.md

这将创建一个本地源文件夹，可以搜索和重新访问，而无需重复提取或粘贴网页到上下文中。

Python MCP服务器

该项目还包括一个Python MCP服务器。

运行方式：

uvx firecrawl-toolkit

MCP客户端配置示例：

{
  "mcpServers": {
    "firecrawl": {
      "command": "uvx",
      "args": ["firecrawl-toolkit"],
      "env": {
        "FIRECRAWL_API_KEY": "<Your Firecrawl API key>",
        "FIRECRAWL_MCP_ENABLE_STDIO": "1"
      }
    }
  }
}

MCP环境变量：

变量	默认值	描述
`FIRECRAWL_API_KEY`	`fc-xxx`	Firecrawl API密钥。
`FIRECRAWL_BASE_URL`	`https://api.firecrawl.dev/v2`	Firecrawl API基本URL。为自托管服务设置此URL。
`FIRECRAWL_HTTP2`	`0`	使用启用HTTP/2 `1`.
`FIRECRAWL_MAX_WORKERS`	`10`	工作进程数。
`FIRECRAWL_MAX_CONNECTIONS`	`200`	最大HTTP连接数。
`FIRECRAWL_MAX_CONCURRENT_REQUESTS`	`200`	最大并发请求数。
`FIRECRAWL_KEEPALIVE`	`20`	最大保持活动连接数。
`FIRECRAWL_RETRY_COUNT`	`3`	最大重试次数。
`FIRECRAWL_RETRY_BASE_DELAY`	`0.5`	基本重试延迟（秒）。
`FIRECRAWL_ENDPOINT_CONCURRENCY`	`{"search":10,"scrape":2}`	每个端点的并发限制。
`FIRECRAWL_ENDPOINT_RETRYABLE`	`{"scrape": false}`	按端点重试配置。
`FIRECRAWL_MCP_ENABLE_STDIO`	`0`	启用STDIO传输。
`FIRECRAWL_MCP_ENABLE_HTTP`	`0`	启用HTTP传输。
`FIRECRAWL_MCP_ENABLE_SSE`	`0`	启用SSE传输。
`FIRECRAWL_MCP_HTTP_HOST`	`127.0.0.1`	HTTP主机。
`FIRECRAWL_MCP_HTTP_PORT`	`7001`	HTTP端口
`FIRECRAWL_MCP_SSE_HOST`	`127.0.0.1`	SSE主机。
`FIRECRAWL_MCP_SSE_PORT`	`7001`	SSE港口
`FIRECRAWL_MCP_LOCK_FILE`	`/tmp/firecrawl_mcp.lock`	锁定文件路径。

STDIO、HTTP和SSE应该一次使用一个。如果需要多次传输，请使用不同的锁文件启动单独的服务。

MCP工具

MCP服务器提供：

工具	说明
`firecrawl-aggregated-search`	聚合网络、新闻和图像搜索。
`firecrawl-web-search`	网络搜索。
`firecrawl-news-search`	新闻搜索。
`firecrawl-image-search`	图像搜索。
`firecrawl-scrape`	抓取一个URL并返回映射的Markdown内容。

对于基于本地shell的代理，Go CLI通常是更简单、更安全的界面，因为它将大型抓取结果写入文件，而不是直接将其返回到模型上下文。

发展

运行Go CLI测试：

cd cli
go test ./...

构建CLI：

cd cli
go build -o firecrawl .

运行Python测试：

pytest

许可证

此项目根据GNU通用公共许可证v3.0或更高版本获得许可。看许可证了解详情。第三方依赖通知和完成许可证文本可在第三条_通知.txt 和 THIRD_PARTY_LICENSES/.

使用说明

Firecrawl工具包

为什么存在此工具包

核心工作流程

1.将网页或PDF抓取到本地Markdown中

2.本地搜索

3.只读相关章节

为什么stdout故意小

内置样板过滤

安装

Python包

Go CLI

API 密钥

API基本URL

CLI命令

常见CLI选项

--proxy

报废命令

基本用途

保存到目录中

剪贴PDF

报废选项

--output

--path

--url

--include-tags

--exclude-tags

--empty-tags

--scroll

--skip-tls

--headers

--headers-file

--timeout

--proxy

学者指挥

学者选择

--query

--search-num

--categories

--time-from

--time-to

--timeout

--proxy

解析命令

解析文档URL

解析本地文件

解析选项

--url

--file

--output

--path

--skip-tls

--timeout

--proxy

音频和视频抓取命令

音频刮擦

视频抓取

推荐使用代理

默认捕获

检查捕获的源

如果页面有噪音

如果内置过滤器删除了有用的东西

搜索命令

搜索选项

--query

--country

--search-num

--search-time

--timeout

--proxy

搜索输出

信贷使用

退出行为

刮擦和解析

搜索、学者、信用使用、音频抓取和视频抓取

示例：本地研究文件夹

Python MCP服务器

MCP工具

发展

许可证

`--proxy`

`--output`

`--path`

`--url`

`--include-tags`

`--exclude-tags`

`--empty-tags`

`--scroll`

`--skip-tls`

`--headers`

`--headers-file`

`--timeout`

`--proxy`

`--query`

`--search-num`

`--categories`

`--time-from`

`--time-to`

`--timeout`

`--proxy`

`--url`

`--file`

`--output`

`--path`

`--skip-tls`

`--timeout`

`--proxy`

`--query`

`--country`

`--search-num`

`--search-time`

`--timeout`

`--proxy`