Skip to main content
Glama

crawl_mcp

基于 crawl4ai 和 FastMCP 的 MCP 服务器,提供网页爬取和搜索功能。

PyPI Version GitHub

功能

爬取 — 自动降级:快速提取 → 浏览器渲染

工具

用途

crawl_single

单个明确 URL 的正文提取

crawl_batch

多个明确 URL 的并行提取

crawl_site

从入口页递归爬取站内页面

搜索 — 基于 ddgs,只返回摘要和链接,不抓正文

工具

用途

search_text / search_news / search_books / search_videos

网页 / 新闻 / 图书 / 视频搜索

search_images

图片搜索,支持下载到本地和 AI 分析

可选 — 需要自备 API Key:llm_config LLM 后处理(实验性)、search_images 的 analyze=true 图片分析。

不配置任何 Key 时,全部爬取和搜索工具照常可用。

Related MCP server: Deep Search MCP Server

性能

场景

耗时

路径

单页(静态)

~0.5s

快速提取

单页(SPA)

~23s

浏览器降级

单页(SPA),配了 Cloud key

~1.2s

Cloud 兜底

10 页(全静态)

~0.5s

并行快速提取

10 页(混合)

~24s

静态页快速 + SPA 走浏览器

各类搜索

~1.5-2s

ddgs

安装

pip install crawl-mcp

浏览器降级路径(SPA / 动态页)需要 Chromium 二进制,首次使用前装一次:

playwright install chromium   # 约 600MB,或用 crawl4ai-setup 一键安装

只做搜索和静态页提取不需要浏览器。

CLI 用法

安装后附带 crawl 命令,与 MCP 工具共用同一套核心:

crawl https://example.com/article          # 单页,Markdown 打到 stdout
crawl https://example.com/article > page.md
crawl --json https://example.com/article   # 完整 JSON(含 title/method 等)
crawl --browser https://spa-site.com       # 强制浏览器渲染
crawl --cloud https://spa-site.com         # 强制走 Crawl4AI Cloud(需 CRAWL4AI_API_KEY)
crawl https://a.com https://b.com          # 多 URL 并行,输出 JSON
crawl site https://docs.example.com --depth 1 --pages 5   # 站内递归爬取
crawl search "python argparse" -n 5        # 网页搜索
crawl search --news "AI" -n 5              # 新闻搜索(--books / --videos 同理)
crawl images "cat" --download              # 图片搜索并下载,输出本地路径
crawl --css "article" --exclude-css "nav,footer" --browser <url>  # 正文区域控制
crawl auth import --from chrome --site zhihu  # 从本地浏览器导入登录态
crawl auth list                            # 查看所有已配置登录态
crawl auth check zhihu.com --url <登录后页面>  # 真实探测登录态是否有效
crawl --quiet https://example.com          # 不刷浏览器进度日志(只留错误)

退出码:成功 0,任一失败 1。进度日志走 stderr,stdout 只有正文/JSON。crawl-mcp 命令仍用于启动 MCP 服务器。

MCP 配置

{
  "mcpServers": {
    "crawl-mcp": {
      "command": "uvx",
      "args": ["crawl-mcp"]
    }
  }
}

需要 LLM 后处理或图片分析时,再加 env:

{
  "mcpServers": {
    "crawl-mcp": {
      "command": "uvx",
      "args": ["crawl-mcp"],
      "env": {
        "CRAWL_MCP_API_KEY": "your-api-key",
        "CRAWL_MCP_BASE_URL": "https://api.openai.com/v1",
        "CRAWL_MCP_TEXT_MODEL": "glm-4.7",
        "CRAWL_MCP_VISION_MODEL": "glm-4.6v"
      }
    }
  }
}

环境变量

变量

说明

默认值

CRAWL_MCP_API_KEY

LLM 后处理 / 图片分析使用的 API 密钥

-

CRAWL_MCP_BASE_URL

OpenAI 兼容 API 基础 URL

https://api.openai.com/v1

CRAWL_MCP_TEXT_MODEL

LLM 后处理模型名称

glm-4.7

CRAWL_MCP_VISION_MODEL

图片分析模型名称

glm-4.6v

CRAWL4AI_API_KEY

Crawl4AI Cloud key,本地提取失败时的兜底路径

-

CRAWL4AI_CLOUD_FALLBACK

设为 0 关闭 Cloud 兜底

1

CRAWL_MCP_CACHE

设为 0 关闭抓取缓存

1

CRAWL_MCP_CACHE_TTL

正缓存有效期(秒)

3600

CRAWL_MCP_NEG_TTL

负缓存/域名记忆有效期(秒)

300

CRAWL_MCP_CACHE_DIR

缓存目录

~/.cache/crawl_mcp

CRAWL4AI_CLOUD_BUDGET

Cloud 兜底整段预算(秒),超时让位给浏览器

10

CRAWL_MCP_COOKIES

浏览器登录态 cookie,Playwright 格式 JSON 数组(如 [{"name":"session","value":"...","domain":".example.com"}])。所有浏览器路径自动携带,登录墙站点(error_code=login_wall)配它后重试;格式错只告警不阻断

-

CRAWL_MCP_STORAGE_STATE

Playwright storage_state 文件路径(完整登录态:cookies + localStorage)。导出:uv run playwright codegen --save-storage=state.json https://站点/login,弹出的浏览器里登录一次并关闭即保存。比手动搬 cookie 全(SPA 的 token 常在 localStorage),两者可同时配

-

CRAWL_MCP_AUTH_DIR

登录态目录(默认 ~/.crawl_mcp/auth/,每站点一个 storage_state 文件)。爬取时按 URL 的 domain 自动匹配注入(爬 zhihu.com 只带 zhihu 的登录态,不全局广播)。crawl auth import --from chrome/firefox 可直接从本地已登录浏览器解析导入。平台支持:装了 rookie-cookies(pip install rookie-cookies)全平台可用——Windows 含 DPAPI/App-Bound v20(Chrome 127+ 默认加密)、macOS 含 Keychain;不装则仅 Linux(内置 sqlite 解析,Chrome v10/v11 + Firefox 明文),Windows/macOS 会提示安装;crawl auth list 查看、crawl auth check <名称> --url <登录后页面> 探测是否过期。目录内文件是明文登录态,注意权限

~/.crawl_mcp/auth

未配置 CRAWL_MCP_API_KEY 时,传入 llm_config 会跳过 LLM 后处理并返回 llm_skipped, search_images(analyze=true) 会返回配置错误;普通爬取和搜索不受影响。

抓取缓存

成功抓取过的 URL 会按 URL + 参数 缓存在本地,重复抓取直接命中(实测 0.24s → 0.00s), 命中时返回 cached: true 和 cached_age(缓存距今多少秒)。缓存能省掉重复请求, Cloud 计费场景下等于直接省额度。

失败也会缓存,但只缓存「重试也没用」的那类(404、空内容、挑战页),TTL 更短 (CRAWL_MCP_NEG_TTL,默认 300s);超时、限速这类波动不缓存。同一个域名连续 2 次 域名级故障(DNS 解析失败、连接被拒)后直接给出结论,不再走降级链路 (method="domain_memo");404/空内容只按 URL 缓存,不会连累同站其他页面。

rm -rf ~/.cache/crawl_mcp   # 清空缓存

Crawl4AI Cloud 兜底

本地快速提取拿不到内容时默认降级到浏览器(~15-23s)。配了 CRAWL4AI_API_KEY 后会先尝试 Cloud /scrape(~1-2s,云端自动选缓存或浏览器引擎),失败才继续走本地浏览器。返回的 method 字段会标记为 cloud_fallback。

  • key 申请:https://api.crawl4ai.com/dashboard

  • 计费 0.05-0.5 credit/次(社区层每月赠 1000 credit),限速 10 请求/分钟

  • CRAWL4AI_API_KEY 支持逗号分隔多个 key,调用量轮询均摊;某个 key 额度耗尽(402) 或被限速(429)时自动换下一个

  • 不配 key 就不会调用 Cloud,行为与纯本地一致

进程启动时(CLI / MCP 服务器)自动加载项目根目录的 .env,已存在的环境变量优先。

LLM 后处理(实验性)

crawl_single 和 crawl_batch 支持可选的 llm_config:

{
  "instruction": "提取产品信息",
  "schema": {
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "price": {"type": "number"}
    }
  }
}
  • instruction: 提取指令

  • schema: 可选的 JSON Schema(结构化数据提取)

未配置 CRAWL_MCP_API_KEY 时会跳过并在结果中返回 llm_skipped。

工具用法

crawl_single - 单页爬取

已知一个明确 URL、需要正文 Markdown 时使用。自动降级:快速提取 → 浏览器渲染。

{
  "name": "crawl_single",
  "arguments": {
    "url": "https://example.com/article"
  }
}

返回:

{
  "success": true,
  "markdown": "# Article Title\n\nContent...",
  "title": "Article Title",
  "method": "fast_extract",
  "error_code": null,
  "timings": {"fast": 0.3}
}

可选参数:

  • enhanced: 浏览器增强模式——等正文实文本出现即返回(不再盲等,浏览器耗时 砍半:BBC 20s→9s、百度百科 22s→8s)+ Pruning 剪枝去导航/boilerplate(BBC 导航 行 38%→0)+ 随机 UA/拟人信号/删弹窗;代价是图片被剪掉,要图片用 enhanced=false;只在浏览器路径生效

  • prefer_fast: 是否优先快速提取(默认 true,设 false 强制浏览器)

  • min_content_length: 快速提取最小内容长度阈值(默认 200 字符)

  • llm_config: LLM 后处理配置(实验性,需 API Key)

  • css_selector: 只提取匹配元素内的正文(如 "article" / "#content"), 页面导航/侧栏噪声多时用;只在浏览器路径生效,fast 成功时被忽略

  • excluded_selector: 排除匹配的元素(如 "nav,footer,aside";实测 BBC 文章页 链接 100→10);只在浏览器路径生效

  • scan_full_page: 滚动加载整页再提取,无限滚动/长列表页用(实测 dev.to 首页 50k→111k 字);只在浏览器路径生效

强制浏览器增强模式需同时设置 prefer_fast=false 和 enhanced=true。 fallback_reason 仅在发生降级时返回,说明快速提取失败或内容不足的原因。 快速提取路径拿不到页面 HTML 的 <title>,title 可能为空;浏览器和 Cloud 路径有标题。

字段说明:

  • error_code: 失败原因的归类,调用方据此决定重试策略。取值: http_402 / http_403 / http_404 / http_401 / rate_limited / http_5xx / tls_error / js_challenge / antibot / empty_content / timeout / connection_refused / connection_reset / dns_error / no_results / unknown;成功时为 null

  • hint: 失败时给出的下一步建议(换路径 / 换出口 / 修证书…)

  • timings: 各降级阶段的耗时(秒),如 {"fast": 0.3, "cloud": 2.8, "browser": 26.4}

  • cached: 命中本地缓存(含负缓存)时为 true,此时不返回 timings

  • cached_age: 缓存条目距今多少秒——数据可能是旧的,必要时用更短 TTL 重抓

crawl_batch - 批量爬取

已知一组 URL 时使用。并行快速提取所有 URL,只把失败、内容不足或 SPA 骨架页送入后续降级。

{
  "name": "crawl_batch",
  "arguments": {
    "urls": [
      "https://example.com/a",
      "https://example.com/b"
    ],
    "concurrent": 3
  }
}

可选参数:

  • concurrent: 浏览器 fallback 并发数(默认 3)

  • prefer_fast: 是否优先快速提取(默认 true,设 false 时所有 URL 直接走浏览器)

  • min_content_length: 快速提取最小内容长度阈值(默认 200 字符)

  • llm_config: LLM 后处理配置(实验性,需 API Key)

  • llm_concurrent: LLM 后处理并发数(默认 3)

  • css_selector / excluded_selector: 正文区域指定/噪声区域排除, 适合一批同构页面(如全部是 article 结构);只在浏览器路径生效

返回结果列表,每项结构同 crawl_single。

crawl_site - 递归爬站

只有网站入口、希望沿站内链接发现并抓取若干页面时使用。入口页快速提取成功时走快速 BFS (从 Markdown 提站内链接,逐层批量爬取、每页自动降级);入口页是 SPA 或失败时退回浏览器 BFS。不支持 LLM 后处理。

{
  "name": "crawl_site",
  "arguments": {
    "url": "https://example.com",
    "depth": 2,
    "pages": 10,
    "concurrent": 3
  }
}

参数:

  • depth: 最大链接深度(默认 2)

  • pages: 最大页面数(默认 10)

  • concurrent: 浏览器爬取并发数(默认 3)

返回 successful_pages、total_pages、success_rate 和 results。

search_text - 网页搜索

搜索工具只返回摘要和链接,不抓页面正文;需要正文再对结果 URL 调 crawl_single 或 crawl_batch。

{
  "name": "search_text",
  "arguments": {
    "query": "Python 快速排序算法",
    "region": "cn-zh",
    "max_results": 5
  }
}

返回:

{
  "success": true,
  "query": "Python 快速排序算法",
  "count": 5,
  "results": [
    {"title": "...", "href": "https://...", "body": "..."}
  ]
}

search_images - 图片搜索

{
  "name": "search_images",
  "arguments": {
    "query": "cute cat",
    "max_results": 10,
    "download": true,
    "download_count": 5,
    "analyze": true,
    "analysis_prompt": "描述这张图片的内容和风格"
  }
}

返回:

{
  "success": true,
  "query": "cute cat",
  "search_results": {"count": 10, "results": [...]},
  "download_results": {"total": 5, "downloaded": 5, ...},
  "analysis_results": {"count": 5, "results": [...]}
}

search_books / search_videos

用法同 search_text。返回字段由 ddgs 上游决定,通常包含标题、链接、摘要或媒体信息,会随来源变化。

开发

uv sync
uv run pytest
uv run python -m crawl4ai_mcp.fastmcp_server --http

Benchmark

docs/BENCHMARK.md 由 scripts/bench.py 自动生成,记录代表性渠道(政府政策、学术期刊、 代码托管、公众号)的命中路径、耗时和搜索命中率。

用例带预期:成功 要求正文 ≥200 字,成功·含关键内容 还要求正文出现指定短语 (expect_text,借鉴 Firecrawl 数据集的 truth_text——抓到了 ≠ 抓对了), 失败·<error_code> 是已知问题站点的回归用例 ——不要求跑通,只要求「失败得对」,error_code 变了就是判定逻辑退化。 数据集在 scripts/bench.yml,加/改用例只动这个文件;页面类型对照公开 benchmark(WCXB / TRACE)的网站池:学术、政府、代码、工具文档、电商、论坛、 新闻、SaaS、招聘。

uv run python scripts/bench.py            # quick:16 用例 + 2 站内 + 6 query,约 2 分钟
uv run python scripts/bench.py --full     # 完整数据集
uv run python scripts/bench.py --repeat 3 # 每个搜索 query 跑 3 次,看命中率
uv run python scripts/bench.py --no-write # 只打印,不写文件

报告含五块:按渠道分组的爬取表(带 fast/cloud/browser 分段耗时和与上次的对比)、 搜索命中率、缓存命中(冷启动 vs 命中)、批量吞吐(crawl_batch 相对逐个抓的加速比)、 站内爬取(crawl_site 快速 BFS 的收页数和耗时)。

文档自动更新,改完代码不用手动维护:

  • 提交时 pre-commit hook 自动重跑(源码未变则跳过),结果写进本次提交

  • Claude Code 会话结束时同样自动重跑(.claude/settings.json 的 Stop hook)

网络不可用时保留上次结果,不阻塞提交。

许可证

MIT License

Available Tools

8 tools
crawl_batchA

批量爬取多个网页(自动降级版)

适用于已经有一组明确 URL、需要并行抓取多个页面的场景。 默认对所有 URL 并行快速提取;只有失败、内容过短或 SPA 骨架页才进入浏览器 fallback。 若只有一个 URL,请使用 crawl_single;若只有入口页并希望发现站内链接,请使用 crawl_site。

参数组合:

  • prefer_fast=True:静态页走快速路径,失败项才走浏览器 fallback。

  • prefer_fast=False:所有 URL 都直接走浏览器,不返回 fast/fallback 方法标记。

  • min_content_length 只影响快速提取是否被认为足够完整。

Inputs: urls (required), concurrent, llm_config, prefer_fast, +2 more. Returns: result

crawl_singleA

爬取单个网页(自动降级:快速提取 → 浏览器渲染)

适用于已经知道一个明确 URL、需要提取该页面正文 Markdown 的场景。 默认先尝试轻量级快速提取(适合静态文章/文档页),失败、内容过短或检测到 SPA 骨架页时 自动切换到浏览器渲染。若要从一个入口页继续发现站内链接,请使用 crawl_site; 若已有多个明确 URL,请使用 crawl_batch。

参数组合:

  • 默认 prefer_fast=True:先快提取,必要时 fallback 到浏览器。

  • prefer_fast=False:跳过快速提取,强制直接使用浏览器。

  • enhanced=True:只影响浏览器路径的等待时间;不会单独跳过快速提取。 如需强制浏览器增强模式,请同时设置 prefer_fast=False, enhanced=True。

Inputs: url (required), enhanced, llm_config, prefer_fast, +1 more. Returns: object

crawl_siteA

从入口页开始递归爬取站内页面(浏览器 + BFS 深度爬取)

适用于只有一个网站入口、希望沿站内链接抓取若干页面的场景。 与 crawl_batch 不同,本工具会从起始页发现链接;与 crawl_single/crawl_batch 不同, 本工具不走快速提取自动降级,也不支持 LLM 后处理。

Inputs: url (required), depth, pages, concurrent. Returns: object

search_booksA

搜索图书

适用于查找技术书籍、学术资料、电子书等。

Inputs: query (required), region, max_results. Returns: object

search_imagesA

搜索图片(支持下载和分析)

=== 基础搜索 === query: 搜索关键词 max_results: 搜索结果数量(默认:10)

=== 搜索过滤 === region: 区域代码 (wt-wt/us-en/cn-zh等) safesearch: 安全搜索 (on/moderate/off) timelimit: 时间限制 (d=天, w=周) size: 图片尺寸 (Small/Medium/Large/Wallpaper) color: 颜色过滤 (如 "Red", "Monochrome") type_image: 类型 (photo/clipart/gif/transparent/line) layout: 布局 (Square/Tall/Wide)

=== 下载选项 === download: 是否下载到本地(默认:False) download_count: 下载数量(默认:全部) output_dir: 下载目录(默认:./downloads/images)

=== 分析选项 === analyze: 是否使用图片模型分析(默认:False) analysis_prompt: 分析提示词 analyze_concurrent: 图片分析并发数(默认:3)

=== 返回格式 === { "success": True, "query": "butterfly", "search_results": { "count": 10, "results": [ { "title": "...", "image": "https://...", "thumbnail": "https://...", "width": 1920, "height": 1080, "source": "Bing" }, ... ] }, "download_results": { # 仅当 download=True 时 "total": 5, "downloaded": 5, "output_dir": "./downloads/images" }, "analysis_results": { # 仅当 analyze=True 时 "count": 5, "results": [ { "image": "...", "type": "local", "analysis": "这是一张..." } ] } }

Inputs: query (required), size, color, layout, +11 more. Returns: object

search_newsA

搜索新闻内容

适用于搜索突发新闻、时事、财经、体育等时效性内容。 只返回新闻搜索结果摘要和来源链接,不抓取全文;如需全文,请对结果 URL 再调用 crawl_single。

Inputs: query (required), region, timelimit, safesearch, +1 more. Returns: object

search_textA

搜索网页内容(通用搜索)

适用于搜索技术文档、百科、博客、论坛、教程等网页内容。 只返回搜索结果摘要和链接,不抓取页面正文;如需正文,请对结果 URL 再调用 crawl_single/crawl_batch。

Inputs: query (required), region, timelimit, safesearch, +1 more. Returns: object

search_videosB

搜索视频

适用于查找教程视频、演示视频、课程录像等。

Inputs: query (required), region, timelimit, safesearch, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each search tool targets a distinct content type (videos, images, text, books, news), and each crawl tool specifies a clear scenario (single URL, site discovery, batch URLs). No two tools have overlapping purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: search_* for searching different media types and crawl_* for crawling variants. This is highly predictable.

    Tool Count5/5

    8 tools is well-scoped for a search-and-crawl server. Each tool serves a distinct need with no redundancy or bloat.

    Completeness5/5

    The tool set covers the full search-and-crawl lifecycle: searching multiple content types, extracting page content, batch processing, and site traversal. There are no obvious missing operations for the stated purpose.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Crawl4AI MCP Server is an intelligent information retrieval server offering robust search capabilities and LLM-optimized web content understanding, utilizing multi-engine search and intelligent content extraction to efficiently gather and comprehend internet information.
      155
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides comprehensive search capabilities including web search, content extraction, news search, academic search, and AI-powered multi-source research. Enables natural language access to web content and research through a production-ready MCP server.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A general-purpose MCP server for crawling and extracting structured data from any website. Supports tools for crawling, single-page extraction, search-and-crawl, and schema extraction.
      2
      MIT