内容
# 网络爬虫 MCP
[](README.md) [](lang/README.zh.md) [](lang/README.hi.md) [](lang/README.es.md) [](lang/README.fr.md) [](lang/README.ar.md) [](lang/README.bn.md) [](lang/README.ru.md) [](lang/README.pt.md) [](lang/README.id.md)
<div align="center">
<img src="https://raw.githubusercontent.com/laurentvv/crawl4ai-mcp-llm/main/assets/banner.svg" alt="Crawl4AI MCP Banner" width="800"/>
</div>
一款强大的网络爬虫工具，通过MCP（模型上下文协议）与AI助手集成。该项目允许AI助手爬取网站，提取动态内容，导航链接，并直接保存结构化的Markdown文件。
## 📋 功能特点
- 与AI助手通过MCP原生集成
- 直接向AI返回爬取的Markdown内容
- 提取并呈现内部/外部链接供AI导航
- 网站爬取，支持配置爬取深度
- 详细的爬取结果统计
- 错误和未找到页面处理
- **高级爬取能力**：
- **魔法模式**：绕过反爬虫（如Cloudflare）并模拟真实浏览器行为
- **目标提取**：使用CSS选择器提取所需内容
- **自定义JavaScript**：在提取前执行代码（点击、滚动、表单填写）
- **持久会话**：在请求中保持cookies和状态，适用于认证站点
- **单页应用支持**：等待动态CSS选择器或设置显式提取前延迟
## 🚀 MCP 配置
使用此工具最简单且推荐的方式是通过`uvx`，它会自动从PyPI获取并运行最新发布的版本。
### 前置条件
- 在您的系统上安装 [uv](https://github.com/astral-sh/uv)。
### AI助手设置（例如Claude Desktop, Cline）
在AI助手的MCP配置文件中添加以下内容（例如`cline_mcp_settings.json`或`claude_desktop_config.json`）：
> **Windows用户注意**：强烈建议指定 `--python 3.13` 以避免某些依赖项的编译问题。
**从PyPI（推荐）**:
```json
{
"mcpServers": {
"crawl": {
"command": "uvx",
"args": [
"--python",
"3.13",
"crawl4ai-mcp-llm"
],
"disabled": false,
"autoApprove": [],
"timeout": 600
}
}
}
```
**从GitHub（最新未发布版本）**:
```json
{
"mcpServers": {
"crawl": {
"command": "uvx",
"args": [
"--python",
"3.13",
"--from",
"git+https://github.com/laurentvv/crawl4ai-mcp-llm",
"crawl4ai-mcp-llm"
],
"disabled": false,
"autoApprove": [],
"timeout": 600
}
}
}
```
### 重要：浏览器安装
爬虫使用Playwright处理动态内容。您必须在设置好工具后安装所需的浏览器：
```bash
uv run playwright install chromium
```
## 🖥️ 使用方法
配置完成后，您可以通过让AI助手执行爬取操作来使用爬虫。
### 与Claude/Cline一起使用的示例
- **简单爬取**： "您可以爬取example.com网站并给我一个总结吗？"
- **带选项的爬取**： "您可以爬取https://example.com，深度为3，并包含外部链接吗？"
- **动态内容**： "爬取这个React应用，等待 `.main-content` 选择器加载。"
- **绕过保护**： "爬取example.com，但使用 'magic mode' 绕过反爬虫保护。"
- **目标提取**： "爬取文档网站，但只提取匹配 `h1, p.lead` CSS选择器的内容。"
## 🛠️ 可用参数（MCP工具）
`crawl` 工具接受以下参数：
| 参数 | 类型 | 描述 | 默认值 |
|-----------|------|-------------|---------------|
| `url` | 字符串 | 要爬取的URL（必填） | - |
| `max_depth` | 整数 | 最大爬取深度 | 2 |
| `include_external` | 布尔值 | 是否包含外部链接 | false |
| `verbose` | 布尔值 | 是否启用详细输出 | true |
| `wait_for_selector` | 字符串 | 在提取内容前等待的CSS选择器。适用于单页应用。 | None |
| `return_content` | 布尔值 | 是否直接在MCP响应中返回提取的内容（如果必要，截断至50k字符）。 | true |
| `output_file` | 字符串 | 输出文件路径 | 自动生成 |
| `magic` | 布尔值 | 启用魔法模式，绕过反爬虫并模拟真实浏览器行为 | false |
| `css_selector` | 字符串 | 特定的CSS选择器，用于提取页面中的目标元素 | None |
| `js_code` | 字符串 | 在提取前在页面上执行的自定义JavaScript代码 | None |
| `session_id` | 字符串 | 持久会话标识符，用于在请求中保持cookies和浏览器状态 | None |
| `delay_before_return_html` | 数值 | 在提取HTML前等待的秒数（适用于重度JS页面） | None |
## 👨💻 开发
如果您想修改爬虫或在本地运行：
1. 克隆此仓库：
```bash
git clone https://github.com/laurentvv/crawl4ai-mcp-llm
cd crawl4ai-mcp-llm
```
2. 使用 `uv` 安装依赖：
```bash
uv sync
```
3. 使用官方MCP检查器在本地测试MCP服务器：
```bash
npx -y @modelcontextprotocol/inspector uv run crawl4ai-mcp-llm
```
4. 运行自动化测试套件：
```bash
uv run pytest tests/
```
5. 直接运行MCP服务器（适用于标准使用）：
```bash
uv run crawl4ai-mcp-llm
```
## 🤝 贡献
欢迎贡献！请随意提出问题或提交拉取请求。
## 📄 许可证
该项目根据MIT许可证授权 - 有关详细信息，请参阅LICENSE文件。
