CloudScraper MCP服务器
模型上下文协议服务器，使AI代理能够绕过Cloudflare保护并抓取web内容
](https://www.python.org/downloads/)    ](DOCKER.md)
______________________________________________________________________
核心功能
| 特性 | 描述 |
|---|---|
| Cloudflare旁路 | 使用cloudscraper库自动处理Cloudflare保护 |
| 多个传输 | 支持stdio和HTTP传输协议 |
| 内容物清理 | 将HTML转换为干净、LLM友好的Markdown格式 |
| 智能分块 | 自动将大型响应拆分为10k个令牌块 |
| Docker支持 | 生产就绪的集装箱化部署 |
| 多种方法 | 支持GET和POST HTTP方法 |
| 二进制处理 | 非文本内容的Base64编码 |
| 文件导出 | 将抓取的内容直接保存到磁盘 |
______________________________________________________________________
可用的MCP工具
工具比较
| 工具 | 返回类型 | 用例 | 分块支持 | 文件输出 |
|---|---|---|---|---|
| scrape_url | 字符串（仅内容） | 用于AI处理的快速内容检索 | 是 | 否 |
| scrape_url_raw | 字典（元数据+内容） | 包含标题和时间的完整响应详细信息 | 是 | 否 |
| scrap_url_to_file | 词典（保存确认） | 将内容导出到工作区文件 | 否 | 是 |
______________________________________________________________________
共享参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
url | string | 是 | - | 要抓取的目标URL |
method | string | 否 | “GET” | HTTP方法（GET或POST） |
clean_content | boolean | 否 | true | 将HTML转换为Markdown |
continuation_token | string | 否 | null | 用于检索下一个块的令牌 |
______________________________________________________________________
scrape_url响应字段
| 字段 | 类型 | 描述 |
|---|---|---|
| 响应 | 字符串 | 包含块指令的页面内容（如适用） |
注： 当内容超过10k个令牌时，响应包括嵌入在文本中的继续指令。
______________________________________________________________________
scrape_url_raw响应字段
| 字段 | 类型 | 始终存在 | 描述 |
|---|---|---|---|
status_code | integer | 是 | HTTP响应状态代码 |
headers | object | Yes | 响应标头（逐跳标头已删除） |
content | string | 是 | 页面内容或当前块 |
content_type | string | 是 | 响应的MIME类型 |
response_time | number | Yes | 请求持续时间（秒） |
chunked | boolean | 分块时 | 表示响应已拆分 |
chunk_index | integer | 分块时 | 当前分块编号（从1开始） |
total_chunks | integer | 分块时 | 分块总数 |
continuation_token | string | 当有更多块时 | 下一次块检索的令牌 |
total_tokens | integer | 分块时 | 完整响应中的令牌总数 |
message | string | 分块时 | 人类可读的块状态 |
error | string | 失败时 | 错误描述 |
______________________________________________________________________
scrap_url_to_file参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
url | string | 是 | - | 要抓取的目标URL |
file_path | string | 是 | - | 内容应保存的路径 |
method | string | 否 | “GET” | HTTP方法（GET或POST） |
clean_content | boolean | 否 | false | 保存前将HTML转换为Markdown |
overwrite | boolean | 否 | false | 如果文件存在，则替换它 |
______________________________________________________________________
scrap_url_to_file响应字段
| 字段 | 类型 | 始终存在 | 描述 |
|---|---|---|---|
status_code | integer | 是 | HTTP响应状态代码 |
headers | object | Yes | 响应标头（逐跳标头已删除） |
content_type | string | 是 | 保存内容的MIME类型 |
response_time | number | Yes | 请求持续时间（秒） |
file_path | string | 成功时 | 保存文件的绝对路径 |
bytes_written | integer | 成功时 | 写入磁盘的字节数 |
message | string | 成功时 | 确认消息 |
error | string | 失败时 | 错误描述 |
______________________________________________________________________
安装
先决条件
| 要求 | 版本 | 目的 |
|---|---|---|
| Python | 3.10+ | 运行时环境 |
| uv | 最新 | 依赖关系管理 |
| Git | 任意 | 存储库克隆 |
设置步骤
克隆存储库并安装依赖项：
git clone https://github.com/yourusername/cloudscraper-mcp-server.git
cd cloudscraper-mcp-server
uv sync______________________________________________________________________
配置
传输协议
| 运输 | 最适合 | 配置 |
|---|---|---|
| 标准 | Claude Code、VSCode、直接AI集成 | 默认模式，不需要环境变量 |
| 超文本传输协议 | n8n，Web应用程序，API集成，远程访问 | 需要MCP_TRANSPORT=http |
______________________________________________________________________
环境变量
| 变量 | 默认值 | 选项 | 描述 |
|---|---|---|---|
MCP_TRANSPORT | stdio | stdio，http | 传输协议选择 |
MCP_HOST | 0.0.0.0 | 任何有效的IP | HTTP模式的主机绑定 |
MCP_PORT | 8000 | 任何有效端口 | HTTP模式端口 |
______________________________________________________________________
用法示例
使用Stdio传输运行（默认）
uv run server.py使用HTTP传输运行
MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8000 uv run server.pyClaude代码集成
claude mcp add cloudscraper-mcp \
--type stdio \
--command "uv" \
--args "run" "server.py" \
--directory "/path/to/cloudscraper-mcp-server"VSCode/IDE配置
{
"mcpServers": {
"cloudscraper-mcp": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"server.py"
],
"cwd": "/path/to/cloudscraper-mcp-server"
}
}
}______________________________________________________________________
Docker部署
有关容器化部署说明，请参阅 医生.md
______________________________________________________________________
技术栈
| 组件 | 技术 | 目的 |
|---|---|---|
| 协议 | FastMCP 3.0+ | 模型上下文协议实现 |
| 抓取 | cloudscraper 1.2.71+ | Cloudflare旁路引擎 |
| 压缩 | brotli 1.0.9+ | 响应解压缩 |
| 解析 | beautifulsoup4 4.10.0+ | HTML解析 |
| 转换 | markdownify 0.11.6+ | HTML到Markdown的转换 |
| 分词 | tiktoken 0.5.0+ | 分块代币计数 |
| 测试 | pytest 8.0+ | 集成测试套件 |
______________________________________________________________________
高级功能
响应分块系统
| 特征 | 值 | 描述 |
|---|---|---|
| 每区块最大代币数 | 10000 | 单个响应中的最大令牌数 |
| 块过期 | 2分钟 | 块检索的缓存寿命 |
| 令牌编码 | cl100k_base | tiktoken编码模型 |
| 连续模式 | chunk_id：索引 | 用于顺序检索的令牌格式 |
______________________________________________________________________
安全标头
| 标题 | 值 | 目的 |
|---|---|---|
| 用户代理 | Chrome 120 | 浏览器模拟 |
| Sec-Ch Ua | Chrome/Chromium | 客户端提示 |
| Sec Fetch-\* | cors/同源 | 获取元数据 |
| 来源/参照者 | 自动生成 | 请求合法性 |
______________________________________________________________________
采用CloudScraper和FastMCP制造