Scrapling MCP Server 完全指南:让 AI Agent 通过自然语言完成反反爬网页抓取
Scrapling 的 MCP(Model Context Protocol)Server 把它的整套抓取能力——从带浏览器指纹伪装的快速 HTTP 请求,到能绕过 Cloudflare Turnstile 的隐身浏览器——直接暴露给你正在使用的 AI 聊天机器人或 Agent。读完本文,你将掌握它的安装与接入方式(Claude Desktop / Claude Code / Docker)、全部 10 个工具的参数细节、Streamable HTTP 远程部署与鉴权配置,以及一套经过官方测试验证的 Prompt 技巧,并了解其底层在 scrapling/core/ai.py 中的实现机制。
核心能力:10 个工具覆盖全场景抓取
Scrapling MCP Server 提供 10 个工具,按能力分为四组:
基础 HTTP 抓取
get:带浏览器指纹伪装的快速 HTTP 请求,自动生成与 TLS 版本、HTTP/3 等特性匹配的真实浏览器请求头;bulk_get:get的异步并发版本,可同时抓取多个 URL。
动态内容抓取
fetch:通过 Chromium/Chrome 浏览器抓取动态内容,对请求和浏览器行为有完整控制;bulk_fetch:fetch的异步版本,在同一浏览器的多个标签页中并发抓取多个 URL。
隐身抓取
stealthy_fetch:使用 Scrapling 的隐身浏览器绕过 Cloudflare Turnstile/Interstitial 及其他反爬系统;bulk_stealthy_fetch:stealthy_fetch的异步并发版本。
截图
screenshot:基于已打开的浏览器会话截取 PNG 或 JPEG 页面截图,并以模型可直接"看到"的 image content block 形式返回(而非 base64 字符串),支持整页截图、JPEG 质量参数,以及wait、wait_selector、network_idle等就绪控制。
会话管理
open_session:创建动态或隐身类型的持久浏览器会话,跨多次 fetch 调用保持打开,避免每次请求都重新启动浏览器的开销;close_session:关闭持久会话并释放资源;list_sessions:列出所有活跃浏览器会话及其详情。
在以上工具之上,Server 还内置了这些关键能力:
- 智能内容提取:将网页/元素转换为 Markdown、HTML,或抽取干净文本;
- CSS 选择器支持:在内容交给 AI 之前,先用 CSS 选择器精确锁定目标元素;
- 反爬绕过:应对 Cloudflare Turnstile、Interstitial 等防护;
- 代理支持:用于匿名与地域定向;
- 浏览器伪装:TLS 指纹伪装、与所选浏览器版本匹配的真实请求头;
- 并行处理:多 URL 并发抓取;
- 会话复用:跨请求复用浏览器会话;
- 广告拦截:所有浏览器类工具自动拦截约 3,500 个已知广告与追踪域名,节省 token 并加速页面加载;
- Prompt 注入防护:自动清理隐藏内容(CSS 隐藏元素、aria-hidden、零宽字符、HTML 注释、
<template>标签),防止恶意网站借抓取内容向 AI 注入指令。
为什么选 Scrapling MCP Server?
除了隐身能力与绕过 Cloudflare 的能力外,Scrapling 的 Server 是市面上唯一支持在传给 AI 之前先用 CSS 选择器筛选具体元素的抓取类 MCP 服务。其他 Server 的工作方式是:先提取全部内容,再让 AI 从中找出你需要的字段——这会消耗远超必要的 token(大量无关内容)。Scrapling 允许你传入一个 CSS 选择器,先把内容收窄到你真正需要的部分,再交给 AI,整个流程因此更快更省。
如果你不会写 CSS 选择器也不用担心:可以直接在 Prompt 里让 AI 为你编写选择器并不断尝试不同组合,直到命中目标字段(见下文示例)。
安装
先安装带 MCP 支持的 Scrapling,再确认浏览器依赖已安装:
# 安装 Scrapling 及 MCP server 依赖
pip install "scrapling[ai]"
# 安装浏览器依赖
scrapling install
也可以直接使用 Docker 镜像:
# Docker Hub
docker pull pyd4vinci/scrapling
# GitHub Container Registry
docker pull ghcr.io/d4vinci/scrapling:latest
从 pyproject.toml 可以看到,ai 这个可选依赖组包含 mcp>=2.0.0、markdownify>=1.2.0 以及 scrapling[fetchers](后者又拉入 curl_cffi、playwright、patchright、browserforge 等抓取引擎依赖),也就是说 pip install "scrapling[ai]" 一条命令就装齐了 MCP Server 的全部依赖。
接入 MCP 客户端
以下以 Claude Desktop 和 Claude Code 为例,同样的逻辑适用于任何支持 MCP 的客户端。
注意:
scrapling-mcp命令是 v0.4.13 新增的快捷入口,直接映射到scrapling mcp,方便那些要求"单个命令"的 MCP 注册表与客户端。如果你使用的是更早版本,请改用scrapling命令并将mcp作为第一个参数。当前仓库 pyproject.toml 中注册的版本即为 0.4.13,两个命令都可用。
Claude Desktop
- 打开 Claude Desktop;
- 点击左上角菜单(☰)→ Settings → Developer → Edit Config;
- 添加 Scrapling MCP Server 配置:
"ScraplingServer": {
"command": "scrapling-mcp"
}
如果这是你添加的第一个 MCP Server,把整个文件内容设为:
{
"mcpServers": {
"ScraplingServer": {
"command": "scrapling-mcp"
}
}
}
该操作会在配置不存在时创建、或打开已有的配置文件,文件位置为:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
为稳妥起见,建议使用 scrapling-mcp 可执行文件的完整路径。在终端中执行以下命令获取:
- macOS:
which scrapling-mcp - Windows:
where scrapling-mcp
例如在 Mac 上返回 /Users/<MyUsername>/.venv/bin/scrapling-mcp,则最终配置为:
{
"mcpServers": {
"ScraplingServer": {
"command": "/Users/<MyUsername>/.venv/bin/scrapling-mcp"
}
}
}
Docker 方式
如果使用 Docker 镜像,配置如下:
{
"mcpServers": {
"ScraplingServer": {
"command": "docker",
"args": [
"run", "-i", "--rm", "pyd4vinci/scrapling", "mcp"
]
}
}
}
这与 Dockerfile 中的入口一致:镜像 ENTRYPOINT 为 ["uv", "run", "scrapling"],传入 mcp 参数即启动 MCP Server。同样的逻辑适用于 Cursor、WindSurf 等其他客户端。
Claude Code
使用 Claude Code 时更简单,安装好后在终端执行:
claude mcp add ScraplingServer "/Users/<MyUsername>/.venv/bin/scrapling-mcp"
可执行路径的获取方式同上(which scrapling-mcp / where scrapling-mcp)。
添加完成后,完全退出并重启所用应用。在 Claude Desktop 中,你应该能在聊天输入框右下角看到 MCP Server 指示器(🔧),或在输入框的 "Search and tools" 下拉中看到 ScraplingServer。
自定义浏览器可执行文件
浏览器类工具(fetch、bulk_fetch、stealthy_fetch、bulk_stealthy_fetch 与 open_session)可以指定一个自定义的 Chromium 兼容浏览器可执行文件,替代内置 Chromium,适用于自编译浏览器或轻量浏览器引擎。启动 Server 时传入路径即可对整个 Server 生效:
scrapling-mcp --executable-path "/path/to/chromium"
在 Claude Desktop 配置中则写入 args:
{
"mcpServers": {
"ScraplingServer": {
"command": "/Users/<MyUsername>/.venv/bin/scrapling-mcp",
"args": [
"--executable-path",
"/path/to/chromium"
]
}
}
}
也可以在启动 Server 前设置环境变量 SCRAPLING_EXECUTABLE_PATH。而单次调用仍可通过工具参数 executable_path 覆盖该全局默认值——这一优先级逻辑可以参见 scrapling/core/ai.py 中的 _resolve_executable_path 方法:先取单次调用传入值,取不到再回落到 Server 级默认值,而 Server 级默认值在构造时依次取命令行参数或 SCRAPLING_EXECUTABLE_PATH 环境变量。
连接远程浏览器
open_session 不一定要在本地启动浏览器。传入一个 CDP URL,它就能通过 Chrome DevTools Protocol 连接一个已在运行的浏览器——无论该浏览器在本机、另一台主机上,还是托管浏览器服务商提供的实例。例如这样的 Prompt:
Open a stealthy browser session on wss://cdp.provider.example/session/abc123,
then use it to scrape the product details from https://shop.example.com.
Close the session when you're done.
两种会话类型(dynamic 与 stealthy)都接受 CDP URL,返回的 session_id 照常配合 fetch 与 screenshot 工具使用。URL 可以是 WebSocket 端点(ws:// / wss://,托管浏览器服务商通常提供这种),也可以是你自己以远程调试端口启动的浏览器的 HTTP 端点:
chrome --remote-debugging-port=9222
此时用 cdp_url="http://localhost:9222" 连接(浏览器在其他机器上则换成对端地址)。
需要注意:
- 浏览器已经在运行,因此仅在"启动阶段"生效的选项在 CDP 会话中会被忽略:
headless、real_chrome、executable_path(包括上文的服务级默认值); - 其余选项照常生效(
locale、useragent、proxy、cookies、timezone_id等),因为每个会话会在远程浏览器上创建自己独立的浏览器上下文。
Streamable HTTP 传输模式
从 v0.3.6 起,MCP Server 支持以 "Streamable HTTP" 传输模式替代传统的 "stdio" 传输。不用默认的 stdio:
scrapling-mcp
而改为:
scrapling-mcp --http
此时监听地址默认为 0.0.0.0:8000,两者均可配置:
scrapling-mcp --http --host '127.0.0.1' --port 8000
这些默认值在 scrapling/cli.py 的 mcp 命令定义中可以逐一对应:--http(默认 False)、--host(默认 '0.0.0.0')、--port(默认 8000)、--executable-path、--auth-token、--allowed-host(可重复)。
鉴权与安全
stdio 传输只有启动它的进程能访问;一旦切到 Streamable HTTP,任何能访问该端口的人都可以调用全部工具——包括从运行 Server 的机器上抓取任意 URL。因此,只要监听地址不是 localhost,就应给它一个 token:
scrapling-mcp --http --auth-token "$(openssl rand -hex 32)"
客户端需要在 Authorization 请求头中携带该 token,缺失或错误的请求会被拒绝并返回 401:
{
"mcpServers": {
"ScraplingServer": {
"url": "https://your-server.example.com/mcp",
"headers": {
"Authorization": "Bearer <your-token>"
}
}
}
}
把 token 直接写在命令行上会留在 shell 历史和进程列表中,更推荐用环境变量 SCRAPLING_MCP_AUTH_TOKEN:
export SCRAPLING_MCP_AUTH_TOKEN="<your-token>"
scrapling-mcp --http
当 Server 监听在公网地址时,还应指定接受的主机名,这会启用 DNS-rebinding 攻击防护(防止你浏览器访问的网页反过来"对话"你的 Server),该选项可重复使用:
scrapling-mcp --http --allowed-host 'your-server.example.com:8000'
实现层面的对应关系:scrapling/core/ai.py 中,_StaticTokenVerifier 用 hmac.compare_digest 做常量时间比较来校验 Bearer token;_transport_security 方法把 --allowed-host 列表转换成 mcp SDK 的 TransportSecuritySettings,同时放行 http 与 https 两种 scheme 的 origin;serve 方法则在两种常见误配下打印警告——HTTP 模式下没设 token(提示任何人都能调用所有工具),或 stdio 模式下设了 token(提示该 token 会被忽略)。这些行为在 tests/ai/test_ai_mcp.py 中有对应的测试覆盖。
补充几点注意事项:
- 鉴权仅对 Streamable HTTP 生效,stdio 下设置会被忽略并有警告日志;
- 明文 HTTP 中 token 是明文传输的,对外暴露前应在 Server 前挂一个终结 TLS 的反向代理;
- 这是单个共享密钥,不是按客户端发凭证:所有客户端使用同一 token,轮换 token 需要重启 Server;
- 用
--http启动但不带 token 仍可用于本地场景,Server 会记录一条"未启用鉴权"的警告。
Prompt 实战示例
以下示例摘自官方文档测试过程中使用的 Prompt,从简单到复杂递进(以 Claude Desktop 为例,其他客户端同理)。
1. 基础网页抓取
把网页主内容提取为 Markdown:
Scrape the main content from https://example.com and convert it to markdown format.
Claude 会用 get 工具抓取页面并返回干净可读的内容;失败时会每秒重试、默认重试 3 次,除非你在 Prompt 中另有指示。如果因防护或动态站点等原因取不到内容,它会自动换用其他工具——如果它没这样做,你可以在 Prompt 里明确要求。
更省事的写法是直接指定工具:
Use regular requests to scrape the main content from https://example.com and convert it to markdown format.
这样 Claude 不用猜该用哪个工具。实践中它有时自己选普通请求,有时又没来由地认为浏览器更适合——经验法则:永远在 Prompt 中指明使用哪个工具,省时省钱且结果稳定。
2. 定向数据抽取
用 CSS 选择器提取特定元素:
Get all product titles from https://shop.example.com using the CSS selector '.product-title'.
If the request fails, retry up to 5 times every 10 seconds.
Server 只提取匹配选择器的元素,并以结构化列表返回。默认重试配置对大多数场景足够,这里显式设置是为了应对目标站的连接不稳定。
3. 电商数据采集
Extract product information from these e-commerce URLs using bulk browser fetches:
- https://shop1.com/product-a
- https://shop2.com/product-b
- https://shop3.com/product-c
Get the product names, prices, and descriptions from each page.
Claude 会用 bulk_fetch 并发抓取所有 URL,再分析抽取出的数据。
4. 多步复杂工作流
比如要拿到 PlayStation 商店第一页当前所有动作类游戏:
Extract the URLs of all games in this page, then do a bulk request to them
and return a list of all action games: https://store.playstation.com/en-us/pages/browse
要点是明确指示对收集到的所有 URL 使用 bulk 请求——否则有时它会逐个 URL 单独请求,耗时显著增加。这个 Prompt 大约需要一分钟完成。但"不够具体"的代价是:它实际用了 stealthy_fetch 和 bulk_stealthy_fetch,不必要地消耗了大量 token。更好的 Prompt 是:
Use normal requests to extract the URLs of all games in this page, then do a
bulk request to them and return a list of all action games:
https://store.playstation.com/en-us/pages/browse
而如果你会写 CSS 选择器,还可以直接把选择器交给它,让它几乎瞬间完成:
Use normal requests to extract the URLs of all games on the page below, then
perform a bulk request to them and return a list of all action games.
The selector for games in the first page is `[href*="/concept/"]` and the
selector for the genre in the second request is
`[data-qa="gameInfo#releaseInformation#genre-value"]`.
URL: https://store.playstation.com/en-us/pages/browse
5. 绕过 Cloudflare 防护
如果你判断目标站有 Cloudflare 防护,直接告诉 Claude,而不是让它自己发现:
What's the price of this product? Be cautious, as it utilizes Cloudflare's
Turnstile protection. Make the browser visible while you work.
https://ao.com/product/oo101uk-ninja-woodfire-outdoor-pizza-oven-brown-99357-685.aspx
6. 长流程任务
Extract all product URLs for the following category, then return the prices
and details for the first 3 products.
https://www.arnotts.ie/furniture/bedroom/bed-frames/
优化后的写法:
Go to the following category URL and extract all product URLs using the CSS
selector "a". Then, fetch the first 3 product pages in parallel and extract
each product's price and details.
Keep the output in markdown format to reduce irrelevant content.
Category URL:
https://www.arnotts.ie/furniture/bedroom/bed-frames/
7. 持久会话
抓取同一站点的多页时,用持久浏览器会话避免每次请求都启动新浏览器的开销:
Open a stealthy browser session with 5 pages maximum pool, then use it to scrape
the main details in bulk from the first 5 product pages on https://shop.example.com.
Close the session when you're done.
Claude 会用 open_session 创建持久浏览器,把 session_id 传给 bulk_stealthy_fetch 同时打开所有页面,最后调用 close_session。这比逐页启动新浏览器快得多。
危险提醒:使用持久会话时,结束后务必关闭会话,否则浏览器会一直开着占用资源!
8. 长流程 + 会话综合示例
Use Scrapling MCP to do the following in this order:
1. Open a stealthy browser session with headless mode off.
2. Go to this page and collect the number of stars: https://github.com/D4Vinci/Scrapling
3. From the README, get the URL that shows the number of downloads and go to it.
4. Get the number of downloads and the top 3 countries from the graph.
5. Prepare a report with the results.
6. Close the browser.
最佳实践
1. 选对工具
get:快速、防护简单的站点;fetch:有 JavaScript/动态内容的站点;stealthy_fetch:有防护、Cloudflare、反爬系统的站点。
2. 性能优化
- 多 URL 用 bulk 类工具;
- 关闭不必要的资源(
disable_resources); - 设置合理的超时;
- 用 CSS 选择器做定向提取。
3. 处理动态内容
- SPA 用
network_idle; - 等待特定元素用
wait_selector; - 加载慢的站点调大超时。
4. 数据质量
main_content_only=true排除导航/广告;- 按场景选择
extraction_type(markdown/html/text)。
5. Prompt 注入防护
MCP Server 在 main_content_only 启用时(默认启用)会自动清理抓取内容,剥离恶意网站可能用来向 AI 上下文注入指令的隐藏内容:
- CSS 隐藏元素:
display:none、visibility:hidden、opacity:0、font-size:0、height:0、width:0; - 无障碍隐藏元素:
aria-hidden="true"; - 模板标签:
<template>元素; - HTML 注释:
<!-- ... -->; - 零宽字符:如零宽空格等不可见 Unicode 字符。
该防护对所有 MCP 工具响应自动生效。保持 main_content_only=true(默认值)可获得最大防护。
6. 用会话处理多请求
- 抓取多页时用
open_session创建持久浏览器会话; - 把
session_id传给fetch/stealthy_fetch复用同一浏览器; - 用完务必用
close_session释放资源; - 用
list_sessions检查哪些会话还活着; - dynamic 会话的
session_id只能配合fetch/bulk_fetch,stealthy 会话只能配合stealthy_fetch/bulk_stealthy_fetch——这一点在源码中是硬校验(_get_session会按expected_type检查并抛出明确的ValueError),在 tests/ai/test_ai_mcp.py 的test_session_type_mismatch中也有对应断言; - 给
open_session传自定义session_id可以为会话取有意义的名字(如"search"、"checkout"),否则默认生成随机 12 位十六进制 ID;重复的 ID 会直接抛错,方便你提前发现冲突。
7. 截图
screenshot只能基于已存在的浏览器会话工作,需先调用open_session(dynamic 或 stealthy 均可);- 图片以真正的
ImageContent块返回,模型可以直接"看到"页面,而不是 JSON 里一段 base64; - 需要首屏以下全部内容时用
full_page=True,默认只截可视区域; - 不追求像素级色彩时,用
image_type="jpeg"加quality(0-100)可以得到更小的载荷——对png传quality会直接抛错; fetch使用的wait、wait_selector、network_idle、timeout控制同样可用。
源码级实现要点
结合 scrapling/core/ai.py 的实现,有几个值得了解的机制:
工具注册与内置指令。ScraplingMCPServer._build_server 通过 server.add_tool 注册全部 10 个工具,每个 fetch 工具都开启了 structured_output,返回结构化的 ResponseModel(status + content 列表 + url);screenshot 则不开启结构化输出,因为它返回的是 ImageContent + TextContent 内容块组合。更关键的是 Server 携带了一段 instructions,以协议级方式约束 AI 的行为:未指定工具时先用 get 再逐步升级、多请求用 bulk 版本、多页面任务优先开会话、用 css_selector 收窄内容以省 token、session_id 存在时浏览器级参数(headless、proxy、locale 等)因在会话创建时已固定而被忽略、open_session 用过必须 close_session 等——这正是"官方示例 Prompt 有效"的底层原因。
批量抓取的分页池。bulk_fetch / bulk_stealthy_fetch 的 docstring 注明:超过 50 个 URL 的批次会通过一个 50 并发页面池抓取。对应实现是 _page_pool_size:min(max(len(urls), 1), _MAX_POOL_PAGES),其中 _MAX_POOL_PAGES = 50 与 scrapling/engines/_browsers/_validators.py 中页面数的校验上限保持一致。
内容转换与清洗。所有 fetch 工具的响应最终都经过 _translate_response:它调用 scrapling.core.shell 的 Convertor._extract_content 按 extraction_type 与 css_selector 提取内容,再用 _CONTROL_CHARS_PATTERN 剔除控制字符(tests/ai/test_ai_mcp.py 中的 test_translate_response_strips_control_characters 验证了含 U+0008 的页面不会让 get/fetch 路径崩溃)。block_ads=True 则在每个浏览器会话构造时写死开启,即上文提到的约 3,500 个广告域拦截是默认行为而非可选项。
测试覆盖。tests/ai/test_ai_mcp.py 覆盖了 get/bulk_get/fetch/bulk_fetch/stealthy_fetch/bulk_stealthy_fetch 六个抓取工具,会话生命周期(创建、列表、复用、类型不匹配报错、自定义 ID、重复 ID 报错),以及 executable_path 参数在工具间的传递逻辑,可作为理解各参数实际行为的参考。
法律与伦理提醒
使用 Scrapling MCP Server 抓取数据时,请注意:
- 检查 robots.txt:访问
https://website.com/robots.txt了解抓取规则; - 尊重速率限制:不要以过量请求压垮服务器;
- 服务条款:阅读并遵守目标站点的条款;
- 版权:尊重知识产权;
- 隐私:注意个人数据保护法规;
- 商业用途:确保已获得商业使用授权。
小结
Scrapling MCP Server 的价值可以概括为三点:一是把"HTTP 快速抓取 → 浏览器动态抓取 → 隐身反爬绕过"三级抓取策略完整暴露给 AI,并让 AI 能按 Server 内置指令自动升级工具;二是通过 CSS 选择器前置过滤与 Markdown 化输出,从源头压缩送入模型的 token 量;三是提供持久会话、批量并发、远程 CDP 浏览器连接、Streamable HTTP + 共享 token 鉴权与 DNS-rebinding 防护等工程化能力,使其既能跑在本地桌面客户端,也能以受保护的服务形式部署到远程。从 docs/ai/mcp-server.md 的完整指南、scrapling/core/ai.py 的约千行实现,到 tests/ai/test_ai_mcp.py 的系统性测试,这套 MCP 集成在仓库内有完整、可追溯的证据链。
atomcodeClaude Code 的开源替代方案。连接任意大模型,编辑代码,运行命令,自动验证 — 全自动执行。用 Rust 构建,极致性能。 | An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get StartedRust0622
Hy4-previewHy4 preview 是由腾讯混元团队研发的新一代混合专家(MoE)旗舰模型。模型总参数量 770B,每个 token 激活 49B,主干共包含78层,第一层采用标准 FFN,其余 77 层均为 MoE 结构,每层包含 256 个路由专家与 1 个共享专家,每个 token 激活 top-8 路由专家及共享专家。主干之外原生内置 1 层 MTP(总参数量 10B,激活 0.7B)以支持投机解码。Python00
GLM-5.3GLM-5.3 与 GLM-5.2 使用相同的基座模型——所有提升均来自后训练。与 GLM-5.2 相比,它在复杂编程和长程任务上的表现显著提升。Jinja00
GLM-5.3-FlashGLM-5.3-Flash (320B-A18B),是GLM-5系列的首个原生多模态模型。320B总参数,能力超过GLM-5.2Jinja00
Spark-X2.5-4BSpark-X2.5-4B 旨在让强大的 AI 更实用、更高效、更易获得。在广泛日常任务中表现强劲,涵盖对话、写作、翻译、推理、编码、工具调用以及智能体工作流,并在同等规模的开源模型中取得领先成绩。Spark-X2.5 将面向效率的架构与最高 1M tokens 的原生上下文窗口相结合,并支持 200 多种语言。Python00
Spark-X2.5-1.7BSpark-X2.5-1.7B 旨在让强大的 AI 更加实用、高效且易于获取。这些模型在广泛的日常任务中表现出色,涵盖对话、写作、翻译、推理、编程、工具调用和智能体工作流,并在同等规模的开源模型中取得领先结果。Spark-X2.5 将面向效率的架构与最高 1M tokens 的原生上下文窗口相结合,并支持 200 多种语言。Python00