CrawlEyes MCP Server

CrawlEyes — 面向 AI Agent 的网页抓取与搜索工具包

英语 | 中文

CrawlEyes 为 AI Agent 提供可靠的全文提取（web_extract）和稳健搜索（web_search）后端——让 Agent 能够查看和阅读网页的「眼睛」。该工具基于 Hermes Agent 构建并经过测试。

它还可作为标准 MCP 服务运行，因此任何 MCP 客户端（Claude Desktop、Cursor 及其他 Agent）都能复用相同的搜索和提取功能。

为什么选择 CrawlEyes？

大多数 Agent 工具包只覆盖流程中的一个环节。CrawlEyes 是少有的一体化工具包，无需外部账号即可在防火长城之后运行。

	典型 Agent 工具包	CrawlEyes
🔍 搜索	需要 API 密钥，且在中国通常受阻	✅ SearXNG（可自托管）+ Tavily 无密钥备用方案——零配置、零密钥
📄 提取	需要单独的爬虫，或使用 Firecrawl SaaS	✅ 内置 Crawl4AI 全文提取，噪声去除率约为 89%
🧠 语义重排	很少包含	✅ 本地 fastembed 重排——无需 torch，模型约 50MB
🔌 MCP 服务	通常不提供	✅ 标准 MCP 工具（search + extract + deep_research + sitemap），支持任何客户端
🌐 适用于中国	大多为英文内容，或被 GFW 屏蔽	✅ 已在中国大陆的真实服务器上测试（baidu + yandex）

零 API 密钥。零外部账号。一条命令。 CrawlEyes 是这一领域中唯一将搜索、提取、语义重排和 MCP 集成于单一、适用于中国且可自托管的软件包中的工具包。

功能

能力	位置	重要性
全文提取	scripts/crawl4ai_cli.py	无头浏览器抓取 → 清晰的 Markdown；可处理约 80% 的 JS/动态/被 UA 屏蔽的页面
内容去噪（P1）	crawl4ai_cli.py --noise-filter	通过 Crawl4AI 的 PruningContentFilter 清除导航/广告/评论——在一篇典型文章上测得 24.6k→2.8k 个字符（约 89% 的噪声已移除）
带退避的重试（P3）	crawl4ai_cli.py --retry N	遇到暂时性故障时采用指数退避（1s/2s/4s）
浏览器会话复用（P4）	crawl4ai_cli.py --session NAME	在单个进程中跨多次抓取复用浏览器上下文——每个 URL 无需冷启动
关键词聚焦提取	crawl4ai_cli.py --bm25 KEYWORD	仅保留与关键词相关的段落（实验性功能——BM25 以英语为主，最适用于英文文档）
搜索（主要）	SearXNG（可自托管的元搜索）	注重隐私的搜索聚合器
搜索（备用）	Tavily 无密钥 API	SearXNG 停用或无结果时，无需配置、无需密钥的备用方案
搜索编排	plugins/searxng-tavily/	Hermes 插件提供方：优先使用 SearXNG → 自动回退到 Tavily 无密钥方案；三态断路器（失败 3 次 → 冷却 60s → 半开）+ 共享 SQLite 缓存（TTL 3600s）
语义重排（P2）	scripts/crawl_search_standalone.py	使用 fastembed + BAAI/bge-small-zh-v1.5 对搜索结果进行本地嵌入重排（512 维、无 torch 依赖、约 50MB、带缓存）——将相关结果排在前面。实测：与爬取相关的结果得分为 0.817/0.732，升至顶部；无关结果得分为 0.302/0.139，降至底部
MCP 服务（P5）	scripts/mcp_crawl_server.py	将 search + extract + deep_research + sitemap 作为标准 MCP 工具公开（默认使用 stdio，远程客户端也可使用 streamable-http）。适用于任何 MCP 客户端，无需依赖 Hermes。提取的内容经过净化，可防范提示词注入（移除不可见字符 + 劫持提示词的行）。统一的速率限制 + 指数退避保护每个工具（滑动窗口、按工具计费），避免并发 Agent 调用对下游服务造成过大压力
站点地图发现（P1）	crawleyes/sitemap.py	sitemap(origin) → 解析 sitemap.xml（普通 / gzip / 索引递归），并在必要时回退到 robots.txt，返回去重后的 URL 映射。无需密钥即可发现整个站点的 URL 范围，用于全站抓取或深度研究的种子数据
多格式提取（P0）	extract(..., format=)	markdown（默认）/ fit（去噪）/ raw（未经筛选）/ markdown_with_citations——可按需选择清理程度
适用于 RAG 的接口	crawleyes/rag.py	使用一行代码 markdown(url) / search_markdown(query) → 获取清晰、已净化、可供大模型使用的 Markdown，用于 RAG 语料库
深度研究	crawleyes/deep_research.py	deep_research(topic) → 将主题拆解为子问题 → 搜索 → 提取 → 综合生成带引用的 Markdown 报告。可选使用大模型（任何兼容 OpenAI 的端点）；不使用大模型时会降级为证据汇总模式
验证	scripts/	通过简洁的子进程脚本，按 Hermes 配置文件端到端验证各个后端

项目结构

plugins/searxng-tavily/   Hermes web-search provider plugin (SearXNG → Tavily keyless fallback)
                          + three-state circuit breaker + shared SQLite cache
scripts/
  crawl4ai_cli.py          Universal scraping CLI (URL → Markdown), with denoise/retry/session/BM25
  crawl_search_standalone.py  Standalone search (SearXNG → Tavily) + optional semantic rerank.
                             No Hermes dependency — usable anywhere, powers the MCP server.
  mcp_crawl_server.py      Standard MCP server exposing search + extract + deep_research + sitemap (stdio)
  single_env_check.py      Verify crawl4ai provider registered+available+extracts (one profile)
  verify_searxng_tavily.py Verify searxng-tavily provider: normal path + forced fallback
  agent_link_check.py      Verify full agent tool chain: web_search_tool dispatch + logs

快速开始

1. 安装 Crawl4AI（适用于中国的镜像）

python3 -m venv .venv
# Use Tsinghua PyPI mirror for speed (or any mirror you prefer)
.venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple crawl4ai
# Playwright browser kernel — use npmmirror binary mirror if cdn.playwright.dev is blocked
PLAYWRIGHT_DOWNLOAD_HOST=https://registry.npmmirror.com/-/binary/playwright \
  .venv/bin/python -m playwright install chromium
.venv/bin/crawl4ai-setup

2. 抓取页面

.venv/bin/python scripts/crawl4ai_cli.py https://example.com          # stdout Markdown
.venv/bin/python scripts/crawl4ai_cli.py https://example.com -o out.md  # to file
.venv/bin/python scripts/crawl4ai_cli.py URL --text --max-words 5000   # plain text, truncated

# Multi-format extraction (markdown|fit|raw|markdown_with_citations)
.venv/bin/python scripts/crawl4ai_cli.py URL --format raw              # unfiltered source markdown
.venv/bin/python scripts/crawl4ai_cli.py URL --format markdown_with_citations  # + source URLs

# Respect robots.txt (opt-in, default off)
.venv/bin/python scripts/crawl4ai_cli.py URL --respect-robots

# Denoise nav/ads + retry 3x + reuse session across scrapes
.venv/bin/python scripts/crawl4ai_cli.py URL --noise-filter --retry 3 --session s1

3. 使用搜索 + 重排（独立运行，无需 Hermes）

# Optional: local semantic rerank of results (fastembed + bge-small-zh, auto-downloaded)
.venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple fastembed

# SearXNG first, Tavily keyless fallback, then rerank
SEARXNG_URL=https://your-searxng .venv/bin/python -c "
import sys; sys.path.insert(0, 'scripts')
from crawl_search_standalone import CrawlSearch
r = CrawlSearch(rerank=True).search('your query')
print(r['data']['web'])"

中国网络说明：嵌入模型从 HuggingFace 下载，而 HuggingFace 在中国大陆网络上无法访问。请设置 HF_ENDPOINT=https://hf-mirror.com 和 HF_HUB_DISABLE_XET=1（hf-mirror 不支持 xet 协议，未设置此项时会返回 401）。

4. 作为 MCP 服务运行（适用于任何客户端）

# Any MCP client can connect via stdio (default):
.venv/bin/python scripts/mcp_crawl_server.py
# Exposes tools:
#   search(query, limit)                 - SearXNG → Tavily keyless, rerank, retry+rate-limit
#   extract(url, max_words, format)      - markdown|fit|raw|markdown_with_citations
#   deep_research(topic, num_questions)  - multi-round cited report
#   sitemap(origin, max_urls)            - URL map from sitemap.xml / robots.txt

# Or serve over HTTP (streamable-http) for remote clients:
.venv/bin/python -m crawleyes.mcp_crawl_server --transport http --port 8765 --host 127.0.0.1
#   → clients connect to http://127.0.0.1:8765/mcp
#   (host/port configurable; default 127.0.0.1:8765)

如需在 Hermes 中使用，请添加到 config.yaml：

mcp_servers:
  crawl:
    command: "/path/to/crawl/.venv/bin/python"
    args: ["/path/to/crawl/scripts/mcp_crawl_server.py"]
    timeout: 90
    connect_timeout: 60

4b. Firecrawl 兼容的 /scrape 端点

已经在使用 Firecrawl 的 Python SDK？将其指向 CrawlEyes，即可继续使用现有代码：

.venv/bin/python -m crawleyes.firecrawl_api --port 8899 --host 127.0.0.1
#   POST /v2/scrape  →  { success, data: { markdown, metadata } }
#   GET  /healthz    →  health check

from firecrawl import Firecrawl
fc = Firecrawl(api_url="http://127.0.0.1:8899", api_key="ignored")
doc = fc.scrape(url="https://example.com")   # → { markdown, metadata }

这是 Firecrawl API 的实用子集：由 CrawlEyes 自有的提取引擎提供核心 /scrape 契约（success + data.markdown + data.metadata）。它不实现 Firecrawl 的异步 /crawl 队列、/search 或 /map；设计理由请参阅设计说明。

5. 安装搜索插件（Hermes）

将 plugins/searxng-tavily/ 复制到 Hermes 插件目录，然后运行：

hermes plugins enable web/searxng-tavily
hermes config set web.search_backend searxng-tavily

在 Hermes 配置文件的 .env 中设置 SEARXNG_URL，使其指向你的 SearXNG 实例。如果未设置或无法访问，提供程序会自动回退到无需密钥的 Tavily API（不需要 API 密钥）。

注意：该插件仅对新启动的 Agent 会话生效。

6. 验证

# Requires the Hermes source tree + its venv
venv/bin/python scripts/verify_searxng_tavily.py $HERMES_HOME
venv/bin/python scripts/agent_link_check.py $HERMES_HOME

设计说明

• 分层组合：没有单一工具能满足所有需求。Crawl4AI 负责提取；SearXNG + Tavily 负责搜索；每一层都有经过测试的回退方案。
• 无需密钥的 Tavily 无需配置或账户即可使用，为整个搜索流程提供低成本的韧性保障。
• 断路器仅适用于 SearXNG：Tavily 回退成功不会重置断路器（否则断路器永远不会触发）。只有 SearXNG 自身成功时才会调用 record_success()。
• 共享 SQLite 缓存位于实际用户主目录中（通过 pwd.getpwuid 获取，而非 $HOME——Hermes 配置文件会覆盖它），因此所有配置文件共用一个缓存。WAL + 5s 超时 + try/except 可在并发情况下退化为不使用缓存。
• 语义重排成本低：fastembed（ONNX）避免了约 2GB 的 torch 依赖；模型缓存后只需约 0.6s 即可加载，生成嵌入约需 50ms。
• MCP 服务独立运行：它不会导入 Hermes 内部模块，因此可在任何 Python 3.12 环境中运行，并为任何 MCP 客户端提供服务。
• MCP 传输支持双模式：stdio（默认，适用于标准 MCP 客户端）或 streamable-http（--transport http），因此同一套代码既可服务本地进程，也可服务远程 HTTP 客户端。
• 统一限流采用分层设计：MCP 工具和深度研究内部的搜索/提取共用一个滑动窗口限流器（按工具计费），因此即使在多轮深度研究中，并发 Agent 扇出也无法对 SearXNG/Tavily/Crawl4AI 造成过大压力。

致谢与灵感来源

本项目基于一系列优秀的开源工具构建。此处所有代码均为独立实现（未复制代码），但构想和接口借鉴了以下项目——谨向其作者致以诚挚谢意：

本仓库中的功能	灵感来源	许可证
提取引擎（Crawl4AI 封装）	Crawl4AI — 直接依赖	Apache-2.0
内容降噪（P1）	Readability、GeneralNewsExtractor（构想）	Apache-2.0 / MIT
语义重排（P2）	Vane、Perplexica（构想）	MIT / MIT
带退避的重试（P3）	Crawlee（构想）	Apache-2.0
浏览器会话复用（P4）	camoufox（构想）	MIT
MCP 服务（P5）	playwright-mcp、exa-mcp-server（构想）	Apache-2.0 / MIT
搜索编排 / 回退	SearXNG — 可自托管（官方 Docker 镜像，未修改源代码），仅通过 HTTP API 访问 · Tavily keyless	AGPL-3.0（服务端软件，未链接 / 嵌入）/ 专有 API

设计独立性：此处的实现均从零开始编写——我们研究了上述项目的方法（降噪阈值、重排流程、退避策略、MCP 工具模式），但没有复制其源代码。依赖项已在 requirements.txt 中声明。如果您认为有遗漏或不正确的署名，请提交 issue。

合规性

CrawlEyes 是一款用于合法研究和个人用途的通用抓取工具包。它有意不包含代理池、指纹轮换或 CAPTCHA 求解（规避反爬措施）功能——这些不在项目范围内。

Robots.txt 默认不启用：将 respect_robots=True 传给 extract / markdown（或在 CLI 中使用 --respect-robots），即可检查每个目标站点的 robots.txt（RFC 9309），并拒绝访问其中明确禁止的 URL。默认关闭是为了避免激进或有误的 robots 规则在用户不知情的情况下阻止合法抓取——是否合规由调用者根据具体用途自行判断。大规模抓取前，请务必查看各网站的服务条款。

许可证

MIT — 参见 LICENSE。

---

📮 关注我们

公众号：AI Aperture —— 分享 AI 工程实践、多 Agent 系统与开源项目经验。

扫码关注，获取项目更新与更多技术内容。