Scrapling MCP Server 完全指南让 AI Agent 通过自然语言完成反反爬网页抓取【免费下载链接】Scrapling️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!项目地址: https://gitcode.com/GitHub_Trending/sc/ScraplingScrapling 的 MCPModel Context ProtocolServer 把它的整套抓取能力——从带浏览器指纹伪装的快速 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_getget的异步并发版本可同时抓取多个 URL。动态内容抓取fetch通过 Chromium/Chrome 浏览器抓取动态内容对请求和浏览器行为有完整控制bulk_fetchfetch的异步版本在同一浏览器的多个标签页中并发抓取多个 URL。隐身抓取stealthy_fetch使用 Scrapling 的隐身浏览器绕过 Cloudflare Turnstile/Interstitial 及其他反爬系统bulk_stealthy_fetchstealthy_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这个可选依赖组包含mcp2.0.0、markdownify1.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.jsonWindows%APPDATA%\Claude\claude_desktop_config.json为稳妥起见建议使用scrapling-mcp可执行文件的完整路径。在终端中执行以下命令获取macOSwhich scrapling-mcpWindowswhere 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 连接一个已在运行的浏览器——无论该浏览器在本机、另一台主机上还是托管浏览器服务商提供的实例。例如这样的 PromptOpen 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 youre done.两种会话类型dynamic与stealthy都接受 CDP URL返回的session_id照常配合 fetch 与 screenshot 工具使用。URL 可以是 WebSocket 端点ws:///wss://托管浏览器服务商通常提供这种也可以是你自己以远程调试端口启动的浏览器的 HTTP 端点chrome --remote-debugging-port9222此时用cdp_urlhttp://localhost:9222连接浏览器在其他机器上则换成对端地址。需要注意浏览器已经在运行因此仅在启动阶段生效的选项在 CDP 会话中会被忽略headless、real_chrome、executable_path包括上文的服务级默认值其余选项照常生效locale、useragent、proxy、cookies、timezone_id等因为每个会话会在远程浏览器上创建自己独立的浏览器上下文。Streamable HTTP 传输模式从 v0.3.6 起MCP Server 支持以 Streamable HTTP 传输模式替代传统的 stdio 传输。不用默认的 stdioscrapling-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就应给它一个 tokenscrapling-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_TOKENexport SCRAPLING_MCP_AUTH_TOKENyour-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 的 originserve方法则在两种常见误配下打印警告——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. 基础网页抓取把网页主内容提取为 MarkdownScrape 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-qagameInfo#releaseInformation#genre-value]. URL: https://store.playstation.com/en-us/pages/browse5. 绕过 Cloudflare 防护如果你判断目标站有 Cloudflare 防护直接告诉 Claude而不是让它自己发现Whats the price of this product? Be cautious, as it utilizes Cloudflares Turnstile protection. Make the browser visible while you work. https://ao.com/product/oo101uk-ninja-woodfire-outdoor-pizza-oven-brown-99357-685.aspx6. 长流程任务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 products 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 youre 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_onlytrue排除导航/广告按场景选择extraction_typemarkdown/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-hiddentrue模板标签template元素HTML 注释!-- ... --零宽字符如零宽空格等不可见 Unicode 字符。该防护对所有 MCP 工具响应自动生效。保持main_content_onlytrue默认值可获得最大防护。6. 用会话处理多请求抓取多页时用open_session创建持久浏览器会话把session_id传给fetch/stealthy_fetch复用同一浏览器用完务必用close_session释放资源用list_sessions检查哪些会话还活着dynamic 会话的session_id只能配合fetch/bulk_fetchstealthy 会话只能配合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_sessiondynamic 或 stealthy 均可图片以真正的ImageContent块返回模型可以直接看到页面而不是 JSON 里一段 base64需要首屏以下全部内容时用full_pageTrue默认只截可视区域不追求像素级色彩时用image_typejpeg加quality0-100可以得到更小的载荷——对png传quality会直接抛错fetch使用的wait、wait_selector、network_idle、timeout控制同样可用。源码级实现要点结合 scrapling/core/ai.py 的实现有几个值得了解的机制工具注册与内置指令。ScraplingMCPServer._build_server通过server.add_tool注册全部 10 个工具每个 fetch 工具都开启了structured_output返回结构化的ResponseModelstatuscontent列表 urlscreenshot则不开启结构化输出因为它返回的是ImageContentTextContent内容块组合。更关键的是 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_sizemin(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验证了含 U0008 的页面不会让 get/fetch 路径崩溃。block_adsTrue则在每个浏览器会话构造时写死开启即上文提到的约 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 集成在仓库内有完整、可追溯的证据链。【免费下载链接】Scrapling️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!项目地址: https://gitcode.com/GitHub_Trending/sc/Scrapling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Scrapling MCP Server 完全指南：让 AI Agent 通过自然语言完成反反爬网页抓取
Scrapling MCP Server 完全指南让 AI Agent 通过自然语言完成反反爬网页抓取【免费下载链接】Scrapling️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!项目地址: https://gitcode.com/GitHub_Trending/sc/ScraplingScrapling 的 MCPModel Context ProtocolServer 把它的整套抓取能力——从带浏览器指纹伪装的快速 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_getget的异步并发版本可同时抓取多个 URL。动态内容抓取fetch通过 Chromium/Chrome 浏览器抓取动态内容对请求和浏览器行为有完整控制bulk_fetchfetch的异步版本在同一浏览器的多个标签页中并发抓取多个 URL。隐身抓取stealthy_fetch使用 Scrapling 的隐身浏览器绕过 Cloudflare Turnstile/Interstitial 及其他反爬系统bulk_stealthy_fetchstealthy_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这个可选依赖组包含mcp2.0.0、markdownify1.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.jsonWindows%APPDATA%\Claude\claude_desktop_config.json为稳妥起见建议使用scrapling-mcp可执行文件的完整路径。在终端中执行以下命令获取macOSwhich scrapling-mcpWindowswhere 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 连接一个已在运行的浏览器——无论该浏览器在本机、另一台主机上还是托管浏览器服务商提供的实例。例如这样的 PromptOpen 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 youre done.两种会话类型dynamic与stealthy都接受 CDP URL返回的session_id照常配合 fetch 与 screenshot 工具使用。URL 可以是 WebSocket 端点ws:///wss://托管浏览器服务商通常提供这种也可以是你自己以远程调试端口启动的浏览器的 HTTP 端点chrome --remote-debugging-port9222此时用cdp_urlhttp://localhost:9222连接浏览器在其他机器上则换成对端地址。需要注意浏览器已经在运行因此仅在启动阶段生效的选项在 CDP 会话中会被忽略headless、real_chrome、executable_path包括上文的服务级默认值其余选项照常生效locale、useragent、proxy、cookies、timezone_id等因为每个会话会在远程浏览器上创建自己独立的浏览器上下文。Streamable HTTP 传输模式从 v0.3.6 起MCP Server 支持以 Streamable HTTP 传输模式替代传统的 stdio 传输。不用默认的 stdioscrapling-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就应给它一个 tokenscrapling-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_TOKENexport SCRAPLING_MCP_AUTH_TOKENyour-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 的 originserve方法则在两种常见误配下打印警告——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. 基础网页抓取把网页主内容提取为 MarkdownScrape 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-qagameInfo#releaseInformation#genre-value]. URL: https://store.playstation.com/en-us/pages/browse5. 绕过 Cloudflare 防护如果你判断目标站有 Cloudflare 防护直接告诉 Claude而不是让它自己发现Whats the price of this product? Be cautious, as it utilizes Cloudflares Turnstile protection. Make the browser visible while you work. https://ao.com/product/oo101uk-ninja-woodfire-outdoor-pizza-oven-brown-99357-685.aspx6. 长流程任务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 products 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 youre 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_onlytrue排除导航/广告按场景选择extraction_typemarkdown/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-hiddentrue模板标签template元素HTML 注释!-- ... --零宽字符如零宽空格等不可见 Unicode 字符。该防护对所有 MCP 工具响应自动生效。保持main_content_onlytrue默认值可获得最大防护。6. 用会话处理多请求抓取多页时用open_session创建持久浏览器会话把session_id传给fetch/stealthy_fetch复用同一浏览器用完务必用close_session释放资源用list_sessions检查哪些会话还活着dynamic 会话的session_id只能配合fetch/bulk_fetchstealthy 会话只能配合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_sessiondynamic 或 stealthy 均可图片以真正的ImageContent块返回模型可以直接看到页面而不是 JSON 里一段 base64需要首屏以下全部内容时用full_pageTrue默认只截可视区域不追求像素级色彩时用image_typejpeg加quality0-100可以得到更小的载荷——对png传quality会直接抛错fetch使用的wait、wait_selector、network_idle、timeout控制同样可用。源码级实现要点结合 scrapling/core/ai.py 的实现有几个值得了解的机制工具注册与内置指令。ScraplingMCPServer._build_server通过server.add_tool注册全部 10 个工具每个 fetch 工具都开启了structured_output返回结构化的ResponseModelstatuscontent列表 urlscreenshot则不开启结构化输出因为它返回的是ImageContentTextContent内容块组合。更关键的是 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_sizemin(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验证了含 U0008 的页面不会让 get/fetch 路径崩溃。block_adsTrue则在每个浏览器会话构造时写死开启即上文提到的约 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 集成在仓库内有完整、可追溯的证据链。【免费下载链接】Scrapling️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!项目地址: https://gitcode.com/GitHub_Trending/sc/Scrapling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
