crawl_mcp

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

功能

爬取工具

• crawl_single - 单页爬取（自动降级：快速提取 → 浏览器渲染）
• crawl_site - 递归爬取整个网站
• crawl_batch - 批量爬取（自动降级，三阶段并行优化）

搜索工具

• search_text - 通用网页搜索
• search_news - 新闻内容搜索
• search_images - 图片搜索（支持下载和 AI 分析）
• search_books - 图书/电子书搜索
• search_videos - 视频搜索（含时长、播放量等）

可选 AI 能力

• LLM 后处理（实验性）- 对已爬取的 Markdown 进行 AI 摘要/结构化提取
• 图片分析 - 使用视觉模型分析图片内容

核心定位：专业爬取工具。不配置 API Key 即可使用全部爬取和搜索功能。

性能

crawl_single / crawl_batch 内置自动降级：静态页走快速路径（~0.5s），SPA 自动 fallback 到浏览器。

关键优势：

• 无需手动选择工具：crawl_single 自动判断用快速提取还是浏览器
• 静态页面享受亚秒级速度，SPA 自动降级保证完整性
• 批量爬取智能分流：静态 URL 并行快提取，失败项才走浏览器
• 搜索类工具全部基于 ddgs，秒级响应
• 无需配置任何 API Key 即可使用核心功能

安装

pip install crawl-mcp

MCP 配置

基础配置（推荐，无需 API Key）

默认配置不需要任何 API Key。以下工具都可以直接使用：

• crawl_single / crawl_batch / crawl_site
• search_text / search_news / search_books / search_videos / search_images

只有两类可选能力需要 API Key：

• 传入 llm_config 做 LLM 后处理
• 调用 search_images 且设置 analyze=true 做图片分析

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

可选 AI 配置（仅在需要 LLM / 图片分析时）

如果需要 llm_config 后处理或图片分析，再增加 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_config 时会跳过 LLM 后处理并返回 llm_skipped；search_images(analyze=true) 会返回图片分析配置错误，但普通图片搜索和下载不受影响。

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"
}

可选参数：

• enhanced: 浏览器增强模式，适用于 SPA/慢加载页面；只在浏览器路径生效
• prefer_fast: 是否优先快速提取（默认 true，设 false 强制浏览器）
• min_content_length: 快速提取最小内容长度阈值（默认 200 字符）
• llm_config: LLM 后处理配置（实验性，需 API Key）

若要强制浏览器增强模式，请同时设置 prefer_fast=false 和 enhanced=true。
fallback_reason 仅在快速提取失败后进入浏览器 fallback 时返回。

crawl_batch - 批量爬取多个明确 URL

已知一组 URL、需要并行抓取多个页面时使用。它会先并行快速提取所有 URL，只把失败、内容不足或 SPA 骨架页送入浏览器 fallback。

{
  "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）

返回为结果列表。method 仅在 prefer_fast=true 的快速/降级路径中出现；fallback_reason 仅在单项发生浏览器 fallback 时出现。

crawl_site - 从入口页递归爬站

只有一个网站入口、希望沿站内链接发现并抓取若干页面时使用。它使用浏览器和 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 - 图片搜索

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

{
  "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

发布

当前准备发布版本：0.2.0

发布前检查：

uv run pytest tests/unit
uv run ruff check .
uv run ruff format --check .
uv build

创建并推送 tag 后会触发 GitHub Actions 发布到 PyPI：

git tag v0.2.0
git push origin v0.2.0

许可证

MIT License