CrawlForge MCP Server

为 Claude、Cursor 和任意 MCP 客户端提供 31 种网页抓取、爬取、深度研究和自主提取工具。
从任意网站获取整洁的 Markdown 和结构化 JSON。立即开始并领取 1,000 个免费积分——无需信用卡。

⭐ 在 GitHub 上为我们点星，持续关注项目动态——这确实有助于更多人发现这个项目。

目录

• 为什么选择 CrawlForge？
• CrawlForge 与替代方案的比较
• 快速入门（2 分钟）
• 可用工具
• 定价
• 高级配置
• 使用示例
• 安全与隐私
• 支持
• 参与贡献

🎯 为什么选择 CrawlForge？

• 31 种原生支持 MCP 的工具——网页抓取、爬取、搜索、真实 Google SERP 排名跟踪、深度研究、自主 agent、统一的多格式 scrape、文档处理、隐身浏览、有状态浏览器会话等，可直接从 AI 助手调用。
• 慷慨的免费额度——立即开始即可获得 1,000 个积分，无需信用卡。这是一次性赠送，而非每月发放，且积分永不过期。
• 默认使用本地 LLM——extract_with_llm 开箱即用，可调用本地 Ollama 模型：无需 LLM API 密钥、无需按 Token 付费，数据也不会离开你的设备。云端服务（OpenAI/Anthropic）为可选项。
• 适配 LLM 的输出——一次抓取即可获得整洁的 Markdown、结构化 JSON（由 Schema 驱动）、截图、链接和元数据。
• 自主 agent——用自然语言描述需求；它会规划、收集并整理答案，同时由编排器强制执行硬性限制（最大步骤数、URL 数和运行时长）——无需提供 URL。
• 强化安全防护——每次请求均有 SSRF 防护、默认拒绝的后端允许列表、经过审核的浏览器自动化操作允许列表，以及按工具进行的积分门控。
• 支持所有 MCP 客户端——Claude Desktop、Claude Code、Cursor 和其他任何支持 MCP 的客户端，只需一条命令即可完成配置。

📊 CrawlForge 与其他方案的对比

本对比反映了撰写时公开文档中记载的功能。CrawlForge 采用 MIT 许可证，并以 MCP 为先——可直接接入 AI 编码助手。

🚀 快速开始（2 分钟）

1. 从 NPM 安装

npm install -g crawlforge-mcp-server

2. 设置 API 密钥（必需）

每个工具都需要 CrawlForge API 密钥——新账户注册后即可获得 1,000 点免费试用额度。推荐的方式会通过浏览器登录，因此无需将密钥粘贴到终端中（编码 Agent 可以代你运行此命令并转发 URL）：

crawlforge login

命令会输出一个审批 URL；打开该 URL 并批准后，密钥便会保存到 ~/.crawlforge/config.json。然后运行 crawlforge init，将 MCP 服务注册到客户端。也可以使用交互式向导，它还会配置你的客户端：

npx crawlforge-setup

此向导将：

• 引导你获取免费的 API 密钥
• 安全地配置你的凭据
• 自动配置 Claude Code 和 Cursor（如果已安装）
• 验证设置是否正常运行

没有 API 密钥？ 可在 https://www.crawlforge.dev/signup 免费获取

一步完成设置（v4.6.0+）： crawlforge init 会检测你的 API 密钥、安装 Agent 技能，并将 MCP 配置段幂等合并到 Claude Code、Claude Desktop 和 Cursor 中。使用 crawlforge init --all --yes 可用非交互方式配置所有检测到的客户端。

3. 配置 IDE（若未自动配置）

{
  "mcpServers": {
    "crawlforge": {
      "command": "npx",
      "args": ["-y", "crawlforge-mcp-server"]
    }
  }
}

{
  "mcpServers": {
    "crawlforge": {
      "type": "stdio",
      "command": "crawlforge-mcp"
    }
  }
}

{
  "mcpServers": {
    "crawlforge": {
      "type": "stdio",
      "command": "crawlforge-mcp"
    }
  }
}

export CRAWLFORGE_API_KEY=your_api_key
npm run start:http    # Streamable HTTP endpoint at http://localhost:10000/mcp

使用哪个启动命令？ npx -y crawlforge-mcp-server 无需全局安装，且始终运行已发布的版本（推荐用于 Claude Desktop）。若要全局安装（npm i -g crawlforge-mcp-server），请使用专用的 crawlforge-mcp 可执行文件——它会通过你的 PATH 解析，因此切换 Node/nvm 版本后仍可使用。MCP 客户端通过 stdio 启动服务时，裸命令 crawlforge 仍会启动服务（向后兼容 v4.2.5 之前创建的配置）；在交互模式下，它是 CLI——运行 crawlforge mcp 可手动启动服务。

📊 可用工具

CrawlForge 需要 CrawlForge API 密钥——每项工具均按使用量计费并消耗额度。新账户可获得 1,000 个免费试用额度。请访问 crawlforge.dev/signup 获取密钥。

所有工具（需要 API 密钥）

如需查看完整的权威功能参考（所有工具、CLI 命令、隐蔽引擎、研究工作流），请参阅 SKILL.md。

↑ 返回顶部

💳 定价

每个工具都按用量计费，并且需要 API 密钥。 新账户可获得 1,000 个免费试用额度，无需信用卡即可开始使用。

所有方案均包含：

• 使用全部 31 个工具
• 额度永不过期；付费方案的额度可结转至下个月
• API 访问和 webhook 通知

查看完整定价

🔧 高级配置

环境变量

# Optional: Set API key via environment
export CRAWLFORGE_API_KEY="cf_live_your_api_key_here"

# Optional: Custom API endpoint (for enterprise)
export CRAWLFORGE_API_URL="https://api.crawlforge.dev"
# As of v3.0.18, this variable is validated against an allow-list of CrawlForge backend hosts.

# Optional: Local LLM (Ollama) overrides — extract_with_llm, extract_structured
# and deep_research all use Ollama when no cloud key is set
export OLLAMA_BASE_URL="http://localhost:11434"   # default; set https://ollama.com for Ollama Cloud
export OLLAMA_DEFAULT_MODEL="gemma3:4b"            # optional; unset = pick the best installed model automatically
                                                   # deep_research judges claims with gemma3:12b when it is installed (ollama pull gemma3:12b);
                                                   # conflict detection is on only with that model, or a cloud provider
export OLLAMA_EMBEDDING_MODEL="nomic-embed-text"   # default: OLLAMA_DEFAULT_MODEL; used for semantic ranking in deep_research
export OLLAMA_API_KEY="..."                        # only for authenticated endpoints (required by Ollama Cloud; a local instance needs none)
export DISABLE_OLLAMA="true"                       # skip Ollama entirely and use CSS/keyword fallbacks

# Optional: Cloud LLM keys — only needed when you pass provider: "openai" or "anthropic"
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Optional: limit which tools this client sees — by name, by group, or both (comma-separated)
export CRAWLFORGE_TOOLS="scrape,search_web,extract_content"
export CRAWLFORGE_TOOL_GROUPS="basic,search,scrape"   # unset = all tools; unknown names/groups are ignored with a warning

# Optional: deep_research stealth extraction fallback (v4.6.6) — see below
export RESEARCH_STEALTH_ENGINE="auto"      # auto (default) | camoufox | chromium
export RESEARCH_STEALTH_FALLBACK="true"    # set to "false" to disable entirely
export RESEARCH_MAX_STEALTH_RETRIES="8"    # cap on stealth retries per research run

# Optional: your own proxies for the stealth paths that have no caller to ask —
# the scrape escalation stage, the deep_research retry, the agent, browser_session.
# Comma-separated; a proxy passed on a call always wins. CrawlForge supplies none.
export CRAWLFORGE_STEALTH_PROXIES="http://user:[email protected]:8080"
# Unrelated to the PROXY_ROTATION_* variables, which belong to the localization tool.

# Optional: turn off the clearance jar (on by default) — see "Stealth engines and proxies"
export CRAWLFORGE_CLEARANCE_JAR="off"

# Optional: also refuse private networks (RFC1918, ULA, CGNAT, ...) — see "Security & Approvals"
export SSRF_STRICT="true"

# Optional: the only directories process_document may read local files from (":"-separated, ";" on Windows)
export CRAWLFORGE_ALLOWED_DIRS="$HOME/Documents:$HOME/Downloads"

MCP 规范功能

CrawlForge 跟进当前 MCP 规范（2025-06-18）以及部分实验性扩展：

• 结构化输出 — scrape、map_site、serp_rank、reddit_search、search_web、extract_structured 和 crawl_deep 除常规文本外，还会返回可供机器解析的 structuredContent，并根据已发布的 outputSchema 进行校验；旧版客户端仍可使用文本。
• 可自我纠正的错误 — 现在，无效的工具输入会作为 isError: true 结果返回，调用模型可以读取并据此重试，而不再是原始 JSON-RPC 协议错误。
• JSON Schema 2020-12 工具架构、确定性的 tools/list 排序（便于客户端提示词缓存），以及只读工具的结果可缓存提示。
• 服务、工具和提示词均支持图标。
• 异步任务（实验性）适用于四个长时间运行的工具 — crawl_deep、batch_scrape、deep_research、agent — 供支持轮询的客户端使用；不支持的客户端仍会收到同步结果。

线级示例和客户端兼容性说明，请参阅 docs/mcp-spec-adoption.md。

本地大模型快速入门（使用 Ollama 的 extract_with_llm）

extract_with_llm 默认使用本地 Ollama 模型，无需大模型提供商密钥、无需支付按 Token 计费的大模型费用，数据也不会离开你的机器（但仍会扣除 CrawlForge 额度）。

# 1. Install Ollama:  https://ollama.com
# 2. Pull any model from https://ollama.com/library
ollama pull llama3.2

# 3. Discover what's installed (from your MCP client)
#    list_ollama_models()

# 4. Extract — defaults to Ollama with the model from step 2
#    extract_with_llm({ url: "https://example.com", prompt: "…", model: "llama3.2" })

隐身引擎和代理

每个隐身入口点——scrape（设置 escalate: true）、stealth_mode、browser_session、scrape_with_actions 和 deep_research 重试——现在默认使用 auto：如果已安装 Camoufox（二次开发的 Firefox），则使用它；否则回退到 Chromium，并在结果的 warnings[] 中说明原因。每个结果都会注明实际运行的引擎。显式指定引擎时，行为一如既往——camoufox 会直接报错而不回退；chromium 和 playwright 是同一个引擎（对于 scrape 的 escalate_engine，请写作 playwright）。

在 browser_session 和 scrape_with_actions 中，只有设置 stealth: true 时才会应用引擎——常规路径使用标准 Chromium 池。

auto 并非没有代价。2026-09-21 在 Apple Silicon Mac 上各测量一次（启动，加上一个上下文和一个空白页面）：Chromium 为 148 毫秒、253 MB；Camoufox 为 946 毫秒、667 MB——每次隐身调用大约多耗时 0.8 秒、多占用 400 MB。对于不会拦截的站点上的高流量任务，请固定使用 engine: "playwright"。

CrawlForge 不提供代理，而数据中心代理无法解决拦截问题：Cloudflare 会在运行任何 JavaScript 之前评估 IP 的 ASN 和 TLS/HTTP2 握手，因此浏览器端的补丁无法弥补数据中心地址的问题。请通过 CRAWLFORGE_STEALTH_PROXIES（逗号分隔的 URL）提供自己的住宅网络出口。调用方未传入代理时，升级阶段、stealth_mode、browser_session、scrape_with_actions、deep_research 重试以及 agent 工具的自动隐身重试都会使用该代理；调用时传入的代理始终优先。使用代理时，Camoufox 会根据出口 IP 推导时区、地区设置和地理位置。

**一次解决的验证挑战不会重复解决。**隐身渲染成功通过 Cloudflare 或 DataDome 验证墙后，供应商的通行 Cookie（cf_clearance、__cf_bm、datadome——不包括其他 Cookie）会保存在 ~/.crawlforge/stealth-clearance.json（权限模式为 0600）中，并在后续隐身上下文中重放，但仅限引擎、User-Agent 和代理均相同的情况，且最长不超过 Cookie 自身的有效期，绝不会超过 24 小时。如果渲染仍然遇到验证墙，则会删除这些 Cookie。设置 CRAWLFORGE_CLEARANCE_JAR=off 可禁用此功能。

详情、测量数据和来源：docs/stealth-engines.md。

deep_research 的隐身提取（Camoufox）

deep_research 会自动重试那些会阻止常规抓取路径的来源（Reddit、Quora、论坛以及受 Cloudflare/DataDome 保护的页面会返回 HTTP 403），改用带有真实浏览器指纹的浏览器，然后从渲染后的 HTML 中重新提取内容。重试次数有限（RESEARCH_MAX_STEALTH_RETRIES，默认值为 8，另有单页超时设置），并且按需加载——只有来源确实被阻止时才会加载浏览器组件。

引擎选择（RESEARCH_STEALTH_ENGINE）：

• auto（默认）——优先使用 Camoufox（Firefox 反检测），然后回退到 Chromium 隐身引擎，最后回退到普通抓取。
• camoufox ——强制使用 Camoufox。
• chromium ——强制使用 Chromium 隐身引擎。

Camoufox 能通过阻止无头 Chromium 的防护：在 2026-09-21 使用住宅 IP 进行的一次基准测试中，它是唯一成功通过 Cloudflare Turnstile（indeed.com）和 Akamai（harrods.com）的引擎，这两个站点都阻止了 Chromium 隐身引擎。两个引擎都未能通过 DataDome 或交互式 Turnstile，因此这只是更好的抓取路径，并非绕过防护。要启用它，请安装可选依赖并执行一次性二进制文件下载：

# Camoufox is declared as an optional dependency, so a normal install already pulls it.
# If you installed with --no-optional, add it explicitly:
npm install camoufox

# One-time download of the Camoufox Firefox binary (~130 MB):
npx camoufox fetch

如果没有 Camoufox 二进制文件，deep_research 会静默回退到 Chromium 隐身引擎，然后回退到普通抓取——不会报错，但在防护严格的网站上恢复能力会较弱。设置 RESEARCH_STEALTH_FALLBACK=false 可禁用整个回退机制。

注意： IP 信誉导致的严格封锁（例如 Reddit 边缘节点返回的 403）无法通过来自任何 IP 的无头隐身方式解决，需要使用住宅/移动代理；CrawlForge 不提供此类代理——请通过 CRAWLFORGE_STEALTH_PROXIES 配置服务器使用你自己的代理。详情请参阅 docs/stealth-engines.md。

手动配置

你的配置存储在 ~/.crawlforge/config.json 中：

{
  "apiKey": "cf_live_...",
  "userId": "user_...",
  "email": "[email protected]"
}

📖 使用示例

配置完成后，可在 AI 助手中使用这些工具：

"Search for the latest AI news"
"Extract all links from example.com"
"Crawl the documentation site and summarize it"
"Monitor this page for changes"
"Extract product prices from this e-commerce site"

🔒 安全与隐私

• 安全认证：所有计量工具都需要 API 密钥
• 本地存储：API 密钥安全地存储在 ~/.crawlforge/config.json 中
• 仅使用 HTTPS：所有连接均使用加密的 HTTPS
• 不保留数据：我们不存储抓取的数据，仅存储使用日志
• 速率限制：内置防滥用保护
• 合规性：遵守 robots.txt 和 GDPR 要求

安全与审批

• SSRF 防护：每个抓取的 URL 都会在发送请求前经过验证，每次连接（包括每次重定向跳转，最多 5 次）都会根据实际连接到的地址进行检查；仅允许 http/https，拒绝云元数据主机名（GCP、Azure）。分为两个级别：
  • **默认（Stage 1）**会拦截环回地址（127.0.0.0/8、::1）、未指定地址（0.0.0.0/8、::）、链路本地地址和云元数据地址（169.254.0.0/16，包括 169.254.169.254、fe80::/10）。允许私有网络（RFC1918 10/8、172.16/12、192.168/16、IPv6 ULA）：在你自己的机器上运行时，服务代表你执行操作；读取路由器页面、NAS 或局域网上的内网文档站点是合理用途，而更严格的级别会阻止这些操作。
  • **SSRF_STRICT=true**会额外拦截所有私有和保留地址范围：RFC1918、ULA（fc00::/7）、CGNAT（100.64/10）、组播、保留地址、IPv4 兼容地址（::/96）和 NAT64（64:ff9b::/96）IPv6。如果 Agent 会读取不可信页面（并可能遭受提示词注入，从而被诱导去抓取局域网地址），且不应访问你的本地网络，或者服务器由多人共用，请设置此项。
• 本地文件（通过 sourceType 为 file 或 pdf_file 的 process_document 处理；如果服务面向网络提供服务，则一律拒绝）：路径根据 realpath 判断，因此符号链接按其目标路径处理。只读取 .pdf、.docx、.txt、.md、.html 和 .htm 文件，且不会读取点目录中的任何内容（~/.ssh、~/.aws、~/.config、~/.crawlforge 等）。设置 CRAWLFORGE_ALLOWED_DIRS（目录之间以 : 分隔；Windows 上使用 ;）可将读取范围限制在这些目录内；这些目录中的点目录限制会解除，但扩展名限制仍然生效。
• 后端端点防护（v3.0.18）：服务器自身对 CrawlForge.dev 的调用使用单独的失败时拒绝允许列表（{crawlforge.dev, www.crawlforge.dev, api.crawlforge.dev}，必须使用 HTTPS）。在解析时会拦截将 CRAWLFORGE_API_URL 设置为任意主机的操作。
• 操作允许列表：scrape_with_actions 仅接受 11 种操作类型（snapshot、wait、click、type、press、scroll、screenshot、executeJavaScript、select、hover、navigate）。不存在下载、写入文件或任意跨页面导航的原语；navigate 和初始 URL 一样，受 SSRF 和 robots.txt 限制。
• JavaScript 防护：默认情况下，executeJavaScript 操作会抛出异常。部署时设置 ALLOW_JAVASCRIPT_EXECUTION=true 可启用此操作（不建议在生产环境中启用）。
• MCP Elicitation（v3.6.0）：有四种工具会在执行开销较大的操作前请求用户确认：deep_research（>50 个 URL）、batch_scrape（同步模式，>25 个 URL）、crawl_deep（预计超过 500 个页面）、extract_structured（未配置 LLM 且架构包含超过 3 个必填字段）。积分不足时也会请求确认。确认机制尽力而为：如果 MCP 客户端不支持 elicitation，工具仍会继续执行（失败时放行）。
• 逐工具积分限制：每种工具都由 withAuth() 封装并计量；执行前会检查并扣除积分，且每种工具都必须提供有效的 API key（自 v3.0.18 起，失败时拒绝）。

完整说明请参阅 docs/sandboxing-and-approvals.md。

安全更新

v3.0.3（2025-10-01）：已修复身份验证绕过漏洞。所有用户都必须使用有效的 API key 进行身份验证。

完整的安全策略及漏洞报告方式请参阅 SECURITY.md。

↑ 返回顶部

🆘 支持

• 文档：https://www.crawlforge.dev/docs
• 问题反馈：GitHub Issues
• 电子邮件：[email protected]
• Discord：加入我们的社区

📄 许可证

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

🤝 参与贡献

欢迎参与贡献！请先阅读我们的贡献指南。

由 CrawlForge 团队倾情打造 ❤️

网站 | 文档 | API 参考