crawl4ai-mcp

MCP-Crawl4AI

由 Crawl4AI 驱动的网页爬取模型上下文协议服务

概述

MCP-Crawl4AI 是一个 模型上下文协议 服务，可让 AI 系统访问实时网络。它基于 FastMCP v3 和 Crawl4AI 构建，通过标准化的 MCP 接口提供 4 个工具、2 个资源和 3 个提示词，并由一个生命周期托管的无头 Chromium 浏览器提供支持。

运行时依赖仅有 2 个 — fastmcp 和 crawl4ai。

提示

查看完整文档站点 →

主要功能

• 完全符合 MCP 规范，通过 FastMCP v3 实现，并支持工具注解（readOnlyHint、destructiveHint 等）
• 4 个专用工具，围绕标准的抓取／爬取以及会话生命周期／制品展开
• 3 个提示词，用于常见的大模型工作流（总结、提取架构、比较页面）
• 2 个资源，提供服务配置和版本信息
• 无头 Chromium 作为生命周期单例管理（启动一次，到处复用）
• 多种传输方式 — stdio（默认）和 Streamable HTTP
• 针对大模型优化的输出 — Markdown、清理后的 HTML、原始 HTML 或纯文本
• 标准选项组，涵盖提取、运行时、诊断、会话、渲染和遍历
• 列表和深度遍历，统一使用一个 crawl 契约
• 感知会话的工作流，提供显式关闭会话和获取制品的工具
• 自动设置浏览器 — 检测缺失的 Playwright 浏览器并自动安装

安装

pip install mcp-crawl4ai
mcp-crawl4ai --setup       # one-time: installs Playwright browsers

uv add mcp-crawl4ai
mcp-crawl4ai --setup       # one-time: installs Playwright browsers

docker build -t mcp-crawl4ai .
docker run -p 8000:8000 mcp-crawl4ai

git clone https://github.com/wyattowalsh/mcp-crawl4ai.git
cd mcp-crawl4ai
uv sync --group dev
mcp-crawl4ai --setup

说明

服务会在首次启动时自动检测缺失的 Playwright 浏览器，并尝试自动安装。你也可以随时手动运行 mcp-crawl4ai --setup 或 crawl4ai-setup。

快速开始

mcp-crawl4ai

mcp-crawl4ai --transport http --port 8000

{
  "mcpServers": {
    "crawl4ai": {
      "command": "mcp-crawl4ai",
      "args": ["--transport", "stdio"]
    }
  }
}

claude mcp add crawl4ai -- mcp-crawl4ai --transport stdio

npx @modelcontextprotocol/inspector uv --directory . run mcp-crawl4ai

工具

标准接口现提供 4 个工具：

scrape

使用单一标准封装响应抓取一个 URL 或有数量限制的 URL 列表（最多 20 个）。

• 输入：targets（str | list[str]）以及可选的分组 options
• 支持提取（schema、extraction_mode）、运行时控制、诊断、会话设置、渲染设置和制品捕获
• 返回包含 schema_version、tool、ok、data/items、meta、warnings、error 的标准 JSON 封装

crawl

使用标准遍历控制进行爬取。

• 对有数量限制的列表遍历，使用 options.traversal.mode="list"
• 从单个种子递归进行 BFS/DFS 遍历，使用 options.traversal.mode="deep"
• 与抓取共用选项组和相同的封装格式，并额外支持遍历选项

close_session

关闭通过 options.session.session_id 创建的有状态会话。

get_artifact

获取在 scrape 或 crawl 期间捕获的制品元数据／内容；需启用 options.conversion.capture_artifacts。

选择核心用法还是高级用法

• 核心路径（推荐）： 使用 scrape／crawl 并搭配最少选项（runtime、conversion.output_format、traversal.mode="list"）。对于大多数 Agent 工作流，这样可以保持行为可预测且风险较低。
• 高级路径（显式启用）： 仅在任务结果需要时，使用深度遍历、自定义调度器控制、JS 转换、提取架构和制品捕获。
• 安全预算和门控： 检查 config://server 中的 settings.defaults、settings.limits、settings.policies 和 settings.capabilities，了解当前启用的约束和功能门控，然后再启用高级选项。

资源

提示词

架构

graph TD
    A[MCP Client] -->|stdio / HTTP| B[FastMCP v3]
    B --> C[Tool Router]
    C --> D[scrape]
    C --> E[crawl]
    C --> F[close_session]
    C --> G[get_artifact]
    D & E & F & G --> N[AsyncWebCrawler Singleton]
    N --> O[Headless Chromium]
    B --> P[Resources]
    B --> Q[Prompts]

    style B fill:#4B8BBE,color:#fff
    style N fill:#FF6B35,color:#fff
    style O fill:#2496ED,color:#fff

该服务采用单模块架构：

• FastMCP v3 负责 MCP 协议协商、传输、工具/资源/提示词注册和消息路由
• 由生命周期管理的 AsyncWebCrawler 在服务启动时启动一个无头 Chromium 浏览器，并在所有工具调用间共享；服务退出时会正常关闭浏览器
• 4 个工具函数通过 @mcp.tool() 装饰器定义规范接口
• 2 个资源函数通过 @mcp.resource() 装饰器返回 JSON
• 3 个提示词函数通过 @mcp.prompt 装饰器返回结构化的 Message 列表

重要

没有中间管理器类或自定义 HTTP 客户端。服务将所有抓取工作委托给 crawl4ai 的 AsyncWebCrawler，并将所有协议处理委托给 FastMCP。运行时依赖项仅有 2 个。

配置

测试

# Run all tests
uv run pytest

# Coverage gate (>=90%)
uv run pytest --cov=mcp_crawl4ai --cov-report=term-missing

# Smoke tests only
uv run pytest -m smoke

# Unit tests only
uv run pytest -m unit

# Integration workflow tests
uv run pytest -m integration

# End-to-end workflow tests
uv run pytest -m e2e

# Manual live test (requires browser)
uv run python tests/manual/test_live.py

说明

所有自动化测试都使用 fastmcp.Client(mcp) 在内存中运行，无需浏览器或网络。测试套件会模拟 AsyncWebCrawler，以实现快速、确定性的执行。

贡献

有关设置开发环境、编码规范和拉取请求流程的详情，请参阅贡献指南。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。