Crawl-MCP: crawl4ai 的非官方 MCP 服务器

⚠️ 重要提示：这是一个针对优秀的 crawl4ai 库的非官方 MCP 服务器实现。 与原 crawl4ai 项目无任何关联。

这是一个全面的模型上下文协议 (MCP) 服务器，它将强大的 crawl4ai 库与先进的 AI 功能相结合。从任何来源提取和分析内容：网页、PDF、Office 文档、YouTube 视频等。具备智能摘要功能，可在保留关键信息的同时大幅减少 Token 使用量。

🌟 核心功能

• 🔍 Google 搜索集成 - 7 种优化搜索类型，支持 Google 官方搜索指令

• 🔍 高级网页爬取：支持 JavaScript、深度站点映射、实体提取

• 🌐 通用内容提取：网页、PDF、Word 文档、Excel、PowerPoint、ZIP 压缩包

• 🤖 AI 驱动的摘要：智能减少 Token（最高可达 88.5%），同时保留核心信息

• 🎬 YouTube 集成：无需 API 密钥即可提取视频字幕和摘要

• ⚡ 生产就绪：19 个专用工具，具备完善的错误处理机制

Related MCP server: Crawl4AI MCP Server

🚀 快速开始

前置要求（必须先完成）

• Python 3.11 或更高版本（FastMCP 要求 Python 3.11+）

安装 Playwright 的系统依赖：

Ubuntu 24.04 LTS (需要手动操作)：

# Manual setup required due to t64 library transition
sudo apt update && sudo apt install -y \
  libnss3 libatk-bridge2.0-0 libxss1 libasound2t64 \
  libgbm1 libgtk-3-0t64 libxshmfence-dev libxrandr2 \
  libxcomposite1 libxcursor1 libxdamage1 libxi6 \
  fonts-noto-color-emoji fonts-unifont python3-venv python3-pip

python3 -m venv venv && source venv/bin/activate
pip install playwright==1.55.0 && playwright install chromium
sudo playwright install-deps

其他 Linux/macOS：

sudo bash scripts/prepare_for_uvx_playwright.sh

Windows (以管理员身份运行)：

scripts/prepare_for_uvx_playwright.ps1

安装

UVX (推荐 - 最简单)：

# After system preparation above - that's it!
uvx --from git+https://github.com/walksoda/crawl-mcp crawl-mcp

Docker (生产就绪)：

# Clone the repository
git clone https://github.com/walksoda/crawl-mcp
cd crawl-mcp

# Build and run with Docker Compose (STDIO mode)
docker-compose up --build

# Or build and run HTTP mode on port 8000
docker-compose --profile http up --build crawl4ai-mcp-http

# Or build manually
docker build -t crawl4ai-mcp .
docker run -it crawl4ai-mcp

Docker 功能：

• 🔧 多浏览器支持：Chromium、Firefox、Webkit 无头浏览器

• 🐧 Google Chrome：包含额外的 Chrome Stable 以保证兼容性

• ⚡ 性能优化：预配置了 Docker 浏览器标志

• 🔒 安全性：非 root 用户执行

• 📦 完整依赖：包含所有必需的库

Claude Desktop 设置

UVX 安装： 添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "crawl-mcp": {
      "transport": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/walksoda/crawl-mcp",
        "crawl-mcp"
      ],
      "env": {
        "CRAWL4AI_LANG": "en"
      }
    }
  }
}

Docker HTTP 模式：

{
  "mcpServers": {
    "crawl-mcp": {
      "transport": "http",
      "baseUrl": "http://localhost:8000"
    }
  }
}

针对日语界面：

"env": {
  "CRAWL4AI_LANG": "ja"
}

📖 文档

语言特定文档

• English: docs/ 目录

• 日本語: docs/ja/ 目录

🛠️ 工具概览

网页爬取 (3)

• crawl_url - 提取支持 JavaScript 的网页内容

• deep_crawl_site - 以可配置的深度爬取站点中的多个页面

• crawl_url_with_fallback - 针对反爬虫站点使用回退策略进行爬取

数据提取 (3)

• intelligent_extract - 使用 LLM 从网页中提取特定数据

• extract_entities - 从网页中提取实体（电子邮件、电话等）

• extract_structured_data - 使用 CSS 选择器或 LLM 提取结构化数据

YouTube (4)

• extract_youtube_transcript - 提取带时间戳的 YouTube 字幕

• batch_extract_youtube_transcripts - 从多个 YouTube 视频中提取字幕（最多 3 个）

• get_youtube_video_info - 获取 YouTube 视频元数据和字幕可用性

• extract_youtube_comments - 提取带分页的 YouTube 视频评论

搜索 (4)

• search_google - 使用类型过滤进行 Google 搜索

• batch_search_google - 执行多次 Google 搜索（最多 3 次）

• search_and_crawl - 搜索 Google 并爬取搜索结果前几名

• get_search_genres - 获取可用的搜索类型

文件处理 (3)

• process_file - 将 PDF、Word、Excel、PowerPoint、ZIP 转换为 Markdown

• get_supported_file_formats - 获取支持的文件格式和功能

• enhanced_process_large_content - 使用分块和 BM25 过滤处理大型内容

批量操作 (2)

• batch_crawl - 使用回退策略爬取多个 URL（最多 3 个 URL）

• multi_url_crawl - 基于模式配置的多 URL 爬取（最多 5 个 URL 模式）

💾 将大型结果持久化到磁盘 (token-saver)

所有信息收集工具都接受一个可选的 output_path 参数，该参数将获取到的完整内容直接写入磁盘，并仅返回精简的元数据响应。这使得 LLM 可以获取巨大的页面、长篇 YouTube 字幕或整个批次的内容，而不会耗尽其上下文预算——仅在需要时从保存的文件中读取。

工作原理：

• 单文件工具（如 crawl_url、extract_youtube_transcript）写入一个 .md 文件（或 JSON 类工具写入 .json）——传入绝对文件路径；如果省略扩展名，则会自动添加。除非设置 overwrite=true，否则拒绝覆盖现有的常规文件。

• 批量工具（batch_crawl、multi_url_crawl、deep_crawl_site、search_and_crawl、batch_extract_youtube_transcripts）期望一个绝对目录路径，并为每个 URL 写入一个 .md 文件以及一个 index.json。任何不存在的路径都会被视为目录并创建——包括包含点号的名称，如 /tmp/run.v1。如果路径已作为常规文件存在，则调用被拒绝。batch_crawl / multi_url_crawl 保留其 list 返回形状，并在每个成功项上嵌入 output_file 键。

• 请求字典工具（search_google、batch_search_google、search_and_crawl、batch_extract_youtube_transcripts）直接从其请求字典中读取持久化键。

• 通用参数：output_path（绝对路径；None 或 "" 跳过持久化）、include_content_in_response（默认为 false——当为 true 时，内容也会包含在响应中，仍受任何 content_limit/content_offset/max_content_per_page 切片限制）、overwrite（默认为 false）。

• 写入操作是每个文件原子的（临时文件 + os.replace）；父目录会自动创建；完整的未切片负载在任何切片或工具内部截断之前被持久化，因此即使响应被切片，磁盘上的副本也始终是完整的。

• 批量字典工具（deep_crawl_site、search_and_crawl、batch_extract_youtube_transcripts）会跳过对报告 success=false 的项进行持久化；这些项仍会出现在 index.json 中，且 file: null，以便调用者可以分析尝试列表。

Markdown 单文件示例：

{
  "tool": "crawl_url",
  "arguments": {
    "url": "https://example.com/long-article",
    "output_path": "/tmp/crawl_out/article.md"
  }
}

JSON 结构化提取（自动添加扩展名）：

{
  "tool": "extract_structured_data",
  "arguments": {
    "url": "https://example.com/products",
    "extraction_type": "css",
    "css_selectors": {"price": ".price", "name": "h1"},
    "output_path": "/tmp/crawl_out/products"
  }
}

批量目录模式：

{
  "tool": "batch_crawl",
  "arguments": {
    "urls": ["https://a.example", "https://b.example"],
    "output_path": "/tmp/crawl_out/batch_run1"
  }
}

每个持久化的 Markdown 文件开头都有一个 YAML 前置元数据块，包含 url、title、fetched_at 和 source_tool，以便工件具有自描述性。

🎯 常见用例

内容研究：

search_and_crawl → extract_structured_data → analysis

文档挖掘：

deep_crawl_site → batch processing → extraction

媒体分析：

extract_youtube_transcript → summarization workflow

站点映射：

batch_crawl → multi_url_crawl → comprehensive data

🚨 快速故障排除

安装问题：

1. 以适当的权限重新运行安装脚本

2. 尝试开发安装方法

3. 检查是否安装了浏览器依赖

性能问题：

• 对于 JavaScript 繁重的站点，使用 wait_for_js: true

• 增加加载缓慢页面的超时时间

• 使用 extract_structured_data 进行针对性提取

配置问题：

• 检查 claude_desktop_config.json 中的 JSON 语法

• 验证文件路径是否为绝对路径

• 配置更改后重启 Claude Desktop

🏗️ 项目结构

• 原始库：crawl4ai (作者: unclecode)

• MCP 封装：本仓库 (walksoda)

• 实现：非官方第三方集成

📄 许可证

本项目是 crawl4ai 库的非官方封装。请参阅原始的 crawl4ai 许可证 以了解底层功能。

🤝 贡献

请参阅我们的 开发指南 以获取贡献准则和开发设置说明。

🔗 相关项目

• crawl4ai - 底层网页爬取库

• Model Context Protocol - 本服务器实现的标准

• Claude Desktop - MCP 服务器的主要客户端