PyreCrawl

🔥 PyreCrawl — 为 AI Agent 提供超强网页浏览能力

只需一条命令，就能让任何 AI Agent 掌握整个网络。 抓取、提取、爬取、映射和搜索 — 可自托管、无需 API 密钥、没有速率限制、无需订阅。

PyreCrawl 使用 MCP（Model Context Protocol），这是 Claude、 Cursor、VS Code、Codex、OpenCode、Hermes 及任何兼容 MCP 的 Agent 所采用的标准工具接口。

智能自动回退机制始终优先选择能够成功的最经济方法：

fast HTTP
    │  (403/503/Cloudflare challenge or empty body)
    ▼
stealth browser (real Chromium + Cloudflare solver)
    │  (still blocked, or the page needs full JS rendering)
    ▼
deep processing (LLM-ready markdown, citations, structured extraction)

⚡ 提供的工具

工具	功能
scrape(url, prefer="auto")	单个 URL → 适合大模型的 Markdown
extract(url, schema)	抓取 + 结构化提取（JsonCss schema）
map_site(root, include_pattern=None, limit=200)	列出所有内部 URL
crawl(root, max_pages=5, prefer="auto", include_paths=None, exclude_paths=None, max_depth=0)	多页面爬取，支持路径筛选 + 真正的 BFS 深度
document(url)	PDF/DOCX/PPTX → Markdown（无需浏览器，可选 [docs] extras）
search(query, limit=10)	通过 DuckDuckGo HTML 搜索网页（无需 API 密钥）
search_papers(query, limit=8, source="arxiv", category=None)	通过 arXiv + Crossref 搜索学术论文（无需 API 密钥）— 将 pdf_url 传入 document
batch_scrape(urls[], ...)	一次调用抓取多个 URL — 并行执行、去重、支持缓存
deep_research(query, limit=5, scrape_top=3)	搜索 → 附带 [n] 引文的证据包（不进行大模型综合 — 由你的 Agent 完成）
monitor(url, action, css_selector=None)	检测变更，持久保存快照并生成统一差异
session(session, action, ...)	持久浏览器会话（保留 Cookie）— 登录墙、多步操作流程、屏幕截图
cache(action)	查看/清除/启用/禁用 HTTP 响应缓存
health()	版本信息 + 导入检查

MCP 资源（无需调用工具即可读取的只读状态）： pyrecrawl://cache/stats · pyrecrawl://sessions · pyrecrawl://monitors

MCP 提示词（开箱即用的操作指南）：research(topic) · rag_ingest(site) · watch_page(url)

环境变量

变量	默认值	作用
PYRECRAWL_CACHE	off	1 = 内存 LRU 缓存（128 个页面），或目录路径（为磁盘模式预留）
PYRECRAWL_CACHE_TTL	900	缓存条目的有效时间（秒）
PYRECRAWL_MONITOR_DIR	~/.pyrecrawl/monitors	保存监控快照的位置
PYRECRAWL_NO_TELEMETRY	off	1 = 禁用匿名启动 ping（也遵循 DO_NOT_TRACK=1）

prefer 选项："auto"（默认回退机制） · "fast"（仅 HTTP） · "stealth"（绕过 CF） · "llm"（深度处理）。

---

🚀 安装与使用（一行命令）

1. 安装

UV（推荐 — 一条命令，无需配置 Python）

UV 是一款快速的 Python 包管理器，也会处理 Python 本身 — 无需单独安装 Python。安装一次即可：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

了解更多 UV 信息 →

随后直接运行 PyreCrawl — 无需 venv、无需 pip install、无需下载 Python：

uvx pyrecrawl@latest

或通过 uv tool install 安装（持久安装，推荐日常使用）

uv tool install pyrecrawl

或通过 pipx 安装（替代方案）

pipx install pyrecrawl

或通过 pip 安装到 venv

pip install pyrecrawl

2. 一次性安装浏览器引擎

pyrecrawl setup

此操作将安装 Chromium 和隐身浏览器引擎（约需 2 分钟，仅需安装一次）。

3. 注册到你的 AI Agent

# Auto-detect installed agents and write their MCP configs
pyrecrawl install

# Or target specific agents
pyrecrawl install claude-desktop cursor

# Dry-run to preview what would change
pyrecrawl install --dry-run

支持的 Agent：claude-desktop、claude-code、cursor、vscode、codex、opencode、hermes。

4. 开始聊天

安装并完成注册后，重启你的 Agent（或开始新会话）。然后提问：

“抓取 https://example.com 并总结内容。”

可用工具：

工具	功能
scrape	获取单个 URL → Markdown（遇到 Cloudflare 时自动升级处理）
extract	抓取内容 + 通过 CSS schema 进行结构化提取 → JSON
map_site	枚举根 URL 下的所有内部 URL
crawl	多页爬取：批量发现并抓取
batch_scrape	通过一次并行调用获取多个 URL
search	通过 DuckDuckGo 进行网页搜索，并绕过反机器人机制
search_papers	学术论文搜索（arXiv / Crossref）
deep_research	一次调用完成搜索、抓取和引用——主要研究工具
document	从 PDF/DOCX/PPTX URL 提取文本
monitor	持续跟踪 URL 的内容变化
session	用于应对登录墙的持久浏览器会话
cache	检查或清除响应缓存
health	验证引擎可用性和版本

另有 3 个引导式提示词：research、rag_ingest、watch_page。

快速示例

像平常一样向 Agent 提问即可，无需特殊语法：

你说	Agent 使用
“抓取 https://example.com 并总结内容”	scrape → 返回 Markdown → Agent 总结
“研究 Rust 内存安全漏洞”	deep_research → 搜索 + 抓取 + 引用
“深入研究全球 AI 监管”	deep_research(iterations=3) → 多轮研究并优化查询
“提取此页面中的所有产品名称和价格”	extract → CSS schema → 结构化 JSON
“爬取 https://docs.example.com 并概述内容”	crawl → 多页爬取 → 总结
“监控此页面的价格变化”	monitor → 基线快照 → 定期差异对比
“查找有关 Transformer 注意力机制的论文”	search_papers → arXiv 结果
“当前缓存命中率是多少？”	cache → 统计数据

---

🧠 Skills — 最大限度提升 Agent 的研究质量

PyreCrawl 工具为你的 Agent 提供了双手（抓取、爬取、搜索）。但 Agent 仍需要一颗大脑——指导它何时使用哪种工具、如何串联研究流程，以及遵循哪些防幻觉规则。

PyreCrawl Skills 正是为此而生。

	MCP 工具（本仓库）	Skills（pyrecrawl-skills）
角色	执行网页操作	告诉 Agent 如何使用这些工具
类比	双手	大脑
示例	deep_research(query, iterations=3)	“运行 3 轮，每轮结束后检查遗漏，并为所有内容添加引用”
是否必需？	是（引擎）	否（但建议启用，以提升研究质量）

快速设置：

# 1. Install the tools (you already have this)
uvx pyrecrawl@latest

# 2. Add the research skill to your project
git clone https://github.com/SanggonBoy/pyrecrawl-skills.git /tmp/pyrecrawl-skills
cp /tmp/pyrecrawl-skills/pyrecrawl-research/SKILL.md ./CLAUDE.md  # or .cursorrules / AGENTS.md

不使用 skills： Agent 拥有强大的工具，但会临场发挥。 使用 skills： Agent 遵循经过验证的研究流程，并采用防幻觉保护措施。

---

📚 手动配置（如果 pyrecrawl install 与你的设置不匹配）

Claude Desktop

配置文件

• Linux：~/.config/Claude/claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%AppData%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pyrecrawl": {
      "command": "uvx",
      "args": ["--from", "pyrecrawl", "pyrecrawl", "serve"]
    }
  }
}

Claude Code

配置文件：项目级 .mcp.json

{
  "mcpServers": {
    "pyrecrawl": {
      "command": "uvx",
      "args": ["--from", "pyrecrawl", "pyrecrawl", "serve"]
    }
  }
}

Cursor

配置文件：~/.cursor/mcp.json

{
  "mcpServers": {
    "pyrecrawl": {
      "command": "uvx",
      "args": ["--from", "pyrecrawl", "pyrecrawl", "serve"]
    }
  }
}

VS Code / Copilot

配置文件：.vscode/mcp.json（项目级）

{
  "servers": {
    "pyrecrawl": {
      "command": "uvx",
      "args": ["--from", "pyrecrawl", "pyrecrawl", "serve"],
      "type": "stdio"
    }
  }
}

Codex CLI

配置文件：~/.codex/config.toml

[mcp_servers.pyrecrawl]
command = "uvx"
args = ["--from", "pyrecrawl", "pyrecrawl", "serve"]

OpenCode

配置文件：~/.config/opencode/opencode.json

{
  "mcp": {
    "pyrecrawl": {
      "type": "local",
      "command": ["uvx", "--from", "pyrecrawl", "pyrecrawl", "serve"],
      "enabled": true
    }
  }
}

Hermes

配置文件

• Linux/macOS：~/.hermes/config.yaml
• Windows：%LocalAppData%\hermes\config.yaml

mcp_servers:
  pyrecrawl:
    command: uvx
    args:
      - --from
      - pyrecrawl
      - pyrecrawl
      - serve
    enabled: true

Windows 注意：uvx 必须位于 PATH 中。如果没有，请使用 uvx.exe 的完整路径（例如 C:\Users\<you>\AppData\Local\hermes\bin\uvx.exe）。

---

🧠 梯级如何选择

PyreCrawl 会将每个请求依次交给三个层级处理，并在第一个返回完整、适用于大模型的结果时停止：

关注点	快速层级	隐匿层级	深度层级
静态 HTML 页面	✅ 约 200ms	—	—
受 Cloudflare 保护	❌	✅ Turnstile 求解器	—
JS 密集型 SPA	❌	✅ 真实 Chromium	—
实时 DOM 数据（输入框 .value、JS 状态）	❌	✅ js 参数	—
适用于大模型的 Markdown + 引用	—	—	✅ BM25、fit-markdown
结构化提取（CSS 架构）	—	—	✅
深度爬取（BFS/DFS/BestFirst）	—	—	✅ 自适应

Agent 无需做出选择。每次调用时，prefer="auto" 都会自动处理。

使用 js 和 wait_for 获取实时 DOM 数据

有些网站会将所需数据保存在 DOM 属性中（例如 <input> 的 .value）， 这些数据由 JS 在 XHR 之后写入，因此不会出现在序列化后的 HTML 中。scrape 工具恰好接受两个隐匿层级参数来处理这种情况：

{
  "url": "https://temp-mail.org/id",
  "prefer": "stealth",
  "wait_for": "document.getElementById('mail').value.includes('@')",
  "js": "document.getElementById('mail').value"
}

• wait_for — 一个 JS 谓词表达式，会持续轮询，直到结果为真（受 timeout 限制）。 对于异步加载的数据，请使用它，而不要猜测等待时长。
• js — 一个 JS 表达式，会在页面稳定后执行；返回值会出现在 meta.js_result 中。错误会记录在 meta.js_error 中（仍会返回页面结果， 不会崩溃）。

---

📊 与托管版 Firecrawl 对比

	Firecrawl	PyreCrawl
费用	每月免费 1k 次，之后为每月 $16–333	免费，可自托管
本地大模型支持	❌	✅ Ollama / 任意大模型
绕过 Cloudflare	✅（Fire-Engine，付费）	✅（免费，内置）
Markdown + BM25	✅	✅
自托管	❌	✅
学术论文搜索	❌	✅ arXiv + Crossref（search_papers）
托管搜索 API	✅ /search	⚠️ DuckDuckGo HTML + arXiv/Crossref（无需密钥）

---

🔧 开发

git clone https://github.com/SanggonBoy/PyreCrawl.git
cd PyreCrawl
uv venv --python 3.12 .venv
source .venv/Scripts/activate  # Windows; or .venv/bin/activate on macOS/Linux
uv pip install -e ".[dev]"
python -m playwright install chromium
scrapling install

运行测试

python scripts/selfcheck.py        # real-network smoke test (13 tools + engines)
python scripts/probe_stdio.py      # stdio JSON-RPC probe
python scripts/test_ladder_bug.py  # SPA-shell ladder escalation regression
python scripts/test_js_eval.py     # stealth js/wait_for params regression
python scripts/test_scope_selector.py  # crawl css_selector/max_depth wiring
python scripts/test_link_harvest.py    # map/BFS link purity regression

---

📦 发布

仅限维护者：

git tag vX.Y.Z
git push origin vX.Y.Z

GitHub Actions 会通过可信发布构建并上传到 PyPI。

---

🔔 获取最新动态

PyreCrawl 会在每次启动时检查 PyPI 并报告最新版本——你的 MCP Agent 会自动通过 health() 工具响应获知此信息，并可直接通知你。

手动检查：

pyrecrawl version

升级：

pyrecrawl update   # runs: uv tool upgrade pyrecrawl

**获取新版本通知：**在 GitHub 仓库中点击 Watch → Releases only，以便在发布新版本时收到电子邮件通知。

---

说明

PyreCrawl 会在服务启动时每 24 小时发送一次匿名使用情况 ping——有关发送内容和退出方式，请参阅 隐私。

🔒 隐私——匿名使用情况 ping

PyreCrawl 会在 MCP 服务启动时每 24 小时向外发送一次简短的匿名 ping，以便我们统计真实用户（DAU/MAU），而不是原始下载量。

发送内容（4 个字段，约 100 字节）	永不发送
哈希后的机器 ID（主机名与 MAC 的 SHA-256——无法还原）	你的 IP（不会存储）
PyreCrawl 版本	你抓取的任何 URL
Python 版本	任何页面内容或搜索查询
OS 系列（windows / linux / darwin）	其他任何信息

客户端代码：src/pyrecrawl/telemetry.py（约 90 行，仅使用标准库）· 收集器：workers/telemetry/——可自托管的 Cloudflare Worker + D1，不使用第三方分析服务。

随时退出：

export PYRECRAWL_NO_TELEMETRY=1   # or the industry-standard DO_NOT_TRACK=1

---

📜 卸载

# Remove from all agent configs
pyrecrawl uninstall

# Remove the package
uv tool uninstall pyrecrawl

---

🛡️ 许可证

MIT——请参阅 LICENSE。