crawlport

crawlport

crawlport 是 Agent 通往可读网络的入口，由 Firecrawl 提供支持。给它一个页面，它会返回整洁的 Markdown；给它整个网站，它可以映射页面、抓取某个版块，或批量抓取一组页面；给它一个问题，它可以搜索、从页面中提取符合你所描述架构的结构化字段、跨多个来源进行研究，或起草网站会用来介绍自身的 llms.txt。它既可作为命令行工具运行，也可作为 MCP 服务运行，并且需要 Firecrawl API 密钥。

设置

从 Firecrawl 获取密钥并将其导出：

export FIRECRAWL_API_KEY=<redacted>

如果未设置该变量，每条命令和工具调用都会失败，并显示提及 FIRECRAWL_API_KEY 的错误——不会向任何地方发送任何内容。

安装

npx @reneturcios/crawlport scrape https://example.com/some/page

或者运行容器镜像：

docker run -i -e FIRECRAWL_API_KEY ghcr.io/cloudcorprecords/crawlport

容器默认启动 MCP 服务（见下文）。传入命令行参数即可将其用作命令行工具。

命令行工具

# One page, as markdown (add --formats html,links etc. for more)
crawlport scrape https://example.com/article --only-main-content

# Discover a site's URLs, optionally filtered
crawlport map https://example.com --search pricing --limit 100

# Web search, with locale controls
crawlport search "standing desk reviews" --limit 5 --lang en --country US

# Start a crawl, then poll it with the returned job id
crawlport crawl https://example.com/docs --limit 50 --max-depth 2
crawlport crawl-status <job-id>

# Structured extraction and batch scraping
crawlport extract https://example.com/a https://example.com/b --prompt "pull the price"
crawlport batch-scrape https://example.com/a https://example.com/b
crawlport batch-status <job-id>

# Research and llms.txt
crawlport deep-research "home battery storage costs in 2026" --max-urls 40
crawlport llmstxt https://example.com --max-urls 25

crawlport --version

调用成功时会打印 API 的 JSON 响应。抓取和批量任务在上游以异步方式运行：启动调用会返回一个任务 ID，相应的状态命令会读取其进度和结果。退出码：成功时为 0，API 调用失败（包括缺少密钥）时为 1，用法错误时为 2。

MCP 服务

同一个二进制文件支持两种运行方式。mcp 子命令会启动一个 stdio MCP 服务：

npx -y @reneturcios/crawlport mcp

MCP 客户端配置：

{
  "mcpServers": {
    "crawlport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/crawlport", "mcp"],
      "env": { "FIRECRAWL_API_KEY": "your-key-here" }
    }
  }
}

工具

工具	输入	功能
firecrawl_scrape	url（必填）；formats、onlyMainContent、waitFor、timeout、actions、includeTags、excludeTags、blockAds、proxy（可选）	通过 POST /v1/scrape 抓取一个页面。
firecrawl_map	url（必填）；search、limit、ignoreSitemap	通过 POST /v1/map 列出网站发现的 URL。
firecrawl_search	query（必填）；limit、lang、country、scrapeOptions	通过 POST /v1/search 搜索网页，可选择抓取每条结果。
firecrawl_crawl	url（必填）；limit、maxDepth、allowBackwardLinks、allowExternalLinks、excludePaths、includePaths、scrapeOptions	通过 POST /v1/crawl 开始抓取；返回任务 ID。
firecrawl_check_crawl_status	id（必填）	通过 GET /v1/crawl/{id} 轮询抓取任务。
firecrawl_extract	urls（必填）；prompt、schema、enableWebSearch、allowExternalLinks	通过 POST /v1/extract，使用提示词／架构进行大模型提取。
firecrawl_batch_scrape	urls（必填）；formats、onlyMainContent	通过 POST /v1/batch/scrape 开始批量抓取；返回任务 ID。
firecrawl_check_batch_status	id（必填）	通过 GET /v1/batch/scrape/{id} 轮询批量任务。
firecrawl_deep_research	query（必填）；maxDepth、timeLimit、maxUrls	通过 POST /v1/deep-research 开展多来源研究。
firecrawl_generate_llmstxt	url（必填）；maxUrls、showFullText	通过 POST /v1/llmstxt 生成 llms.txt 内容。

工具结果是上游 JSON，并以文本形式美化输出。仅当提供可选参数时才会转发这些参数，否则使用 API 默认值。上游错误会作为工具错误返回，其中包含 HTTP 状态码和 API 自带的错误消息。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。