网页爬取服务

MCP-Crawl4AI

基于Crawl4AI的web爬行模型上下文协议服务器

概述

MCP-Crawl4AI 是一个 模型上下文协议 服务器，使AI系统能够访问实时网络。建立在 FastMCP v3 和 Crawl4AI，它暴露了 4工具, 2资源，以及 3个提示 通过标准化的MCP接口，由寿命管理的无头Chromium浏览器支持。

只有2个运行时依赖项 — fastmcp 和 crawl4ai.

[！提示] 完整文档网站→

主要特点

• 完全符合MCP 通过带有工具注释的FastMCP v3(readOnlyHint, destructiveHint等等）
• 4个重点工具 以规范的抓取/爬行加会话生命周期/工件为中心
• 3个提示 用于常见的LLM工作流（总结、提取模式、比较页面）
• 2资源 公开服务器配置和版本信息
• 无头铬 作为生命周期单例进行管理（一次启动，随处重用）
• 多个传输 --stdio（默认）和流式HTTP
• LLM优化输出 --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)、运行时控制、诊断、会话设置、渲染设置和工件捕获
• 返回规范JSON信封 schema_version, tool, ok, data/items, meta, warnings, error

crawl

使用规范遍历控件进行爬网。

• options.traversal.mode="list" 用于有界列表遍历
• options.traversal.mode="deep" 用于从单个种子进行递归BFS/DFS遍历
• 在相同的封套形状中共享刮擦选项组和遍历选项

close_session

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

get_artifact

检索期间捕获的工件元数据/内容 scrape 或 crawl 当 options.conversion.capture_artifacts 已启用。

选择核心与高级使用

• 核心路径（推荐）： 使用 scrape/crawl 选择最少(runtime, conversion.output_format, traversal.mode="list").这使大多数代理工作流的行为保持可预测性和低风险。
• 高级路径（明确选择加入）： 仅在任务结果需要时使用深度遍历、自定义调度器控件、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许可证获得许可。请参阅 许可证 文件以获取详细信息。

MCP-Crawl4AI — 将AI连接到实时网络