cute-web-scraper

一个为 Claude 提供网页抓取能力的 MCP 服务器。 免费、本地运行、无需 API 密钥、无需云账户。

用自然语言提问即可。它会抓取页面，在需要时渲染 JavaScript，绕过拦截，并返回干净的 markdown 或可查询的表格——无需选择器，无需胶水代码。

为什么选它

• 进得去。 四级递进方案——纯 HTTP、浏览器 TLS 指纹、真实浏览器，再到隐身浏览器。ASOS、eBay、Booking.com 和 Trustpilot 在家庭网络、无代理的情况下都能返回真实数据。

• 不浪费你的上下文。 文章会剥离导航、Cookie 横幅和页脚：一篇 BBC 新闻页面从 20,513 个字符缩减到 3,198 个。大型结果存入 SQLite 表，用 SQL 查询，而不是粘贴到对话中。

• 如实报告失败。 测试的网站中有五个在成功状态码下返回了拒绝——HTTP 200 下的插页、202 下的机器人检测——还有一个在 403 下返回了真实内容。拦截检测依据的是页面正文而非状态码，因此你不会把占位页当作数据报告。

• 整站抓取，而非单页。 站点地图发现、并行抓取，以及覆盖产品、联系方式、Shopify 目录、地点、PDF 和变更跟踪的 24 个工具。

安装

pipx install git+https://github.com/maccydee/cute-web-scraper

首次使用 js_render 时会自动下载 Chromium（一次性约 130MB）。

Related MCP server: mcp-server-scraper

连接到 Claude Code

claude mcp add cute-web-scraper -- cute-web-scraper

然后直接提问：

Scrape every product from https://example-shop.com and give me a CSV of name and price.

工具

抓取与发现

提取

地点与本地商家

变更跟踪

结果表

一次典型运行会组合使用它们：analyze_website → crawl_site → fetch_pages → query_table。

提取任意字段

extract_by_selector 覆盖了固定提取器无法处理的所有情况：

Get the title, price and link from every product on these 40 pages,
save it as `catalogue`, then show me anything under £50.

fields 将列名映射到 CSS 选择器。row_selector 使每个匹配项成为一行——这就是将列表转换为表格的关键。@attr 后缀读取属性而非文本，href 和 src 会解析为绝对 URL：

{"name": "h3 a@title", "price": ".price_color", "link": "h3 a@href"}

驱动页面

fetch_page 接受 actions 参数，这些操作在读取页面之前执行——Cookie 门、"加载更多"按钮、无限滚动和搜索表单：

[{"action": "click", "selector": "#accept-cookies"},
 {"action": "scroll_to_bottom", "max_rounds": 10}]

可用操作：click、type、press、wait、wait_for、scroll、scroll_to_bottom 和 click_until_gone。每个操作都会报告其执行内容，因此静默未匹配任何内容的步骤也会可见，而不是让你猜测。

读取 API 而非页面

当网站难以解析时，inspect_network 会渲染页面并报告其发出的请求。JavaScript 页面几乎总是从某个端点加载数据，你可以直接抓取该端点——比解析标记更省资源，而且能经受住破坏选择器的改版：

Inspect the network on this listing page, then fetch whatever JSON endpoint it uses.

监控变更

Check https://example.com/pricing for changes.

track_changes 存储快照并报告 new、same 或 changed，附带统一差异格式。这就是无需调度器的监控——随时检查，只看到差异。

斜杠命令

服务器自带四个现成工作流，在 Claude Code 中以斜杠命令形式出现：scrape_site、scrape_shopify_store、find_contacts 和 compare_prices。

处理大型抓取

任何返回行的工具都接受 save_as 参数。它不会将数据放入对话中，而是写入结果表并返回摘要：

Extract the whole catalogue from deathwishcoffee.com into a table called `catalogue`,
then tell me the price range and how many variants are out of stock.

Claude 调用 extract_shopify_store(save_as="catalogue")，获得行数和列列表，然后用 query_table 回答：

SELECT COUNT(*) AS variants, MIN(price) AS cheapest,
       MAX(price) AS dearest, SUM(available) AS in_stock
FROM catalogue

表可容纳 100,000 行，且这些行都不会进入对话。query_table 严格只读——它针对只读的 SQLite 句柄运行，拒绝任何非 SELECT 的内容，因此查询永远不会修改或删除已保存的数据。

表存储在 ~/.cute-web-scraper/results.db 的 SQLite 文件中（设置 SCRAPER_DB_PATH 可更改位置）。

数据清洗

query_table 也接受 save_as 参数，将结果持久化为新表。SQL 已经能表达常见的清洗操作，因此无需单独的编辑工具集：

SELECT DISTINCT * FROM leads                                  -- deduplicate
SELECT street || ', ' || city AS address FROM leads           -- merge columns
SELECT name, phone FROM leads WHERE phone IS NOT NULL         -- drop columns and rows
SELECT vendor AS brand FROM catalogue                         -- rename

除非你故意指定源表自身的名称，否则源表不会被修改；当你这样做时，响应会显示 replaced_existing_table——因此就地筛选绝不会静默丢失行。

地点与本地商家

find_places 查找单个地点；find_places_nearby 返回半径内某类别的所有内容，这正是本地线索生成的场景：

Find every dentist within 4km of Bath, save it as `leads`,
then tell me how many have a website but no phone number.

类别接受友好名称（cafe、dentist、hotel、solicitor、gym、hairdresser……）或原始 OpenStreetMap 标签，如 amenity=dentist。

关于数据源的说明。 这是 OpenStreetMap，而非 Google Maps。Google 是显而易见的目标，但它行不通：自动化浏览器会遇到 Cookie 同意插页，即使通过后，也只是一个没有地点面板的降级地图外壳。隐身层级也无济于事，因为这是同意墙而非机器人检测——与隐身所解决的问题不同。

OpenStreetMap 通过有文档记录的开放端点提供相同字段——名称、地址、坐标、电话、网站、营业时间、类别——且无需密钥。唯一没有对应物的是星级评分和评论数量，这些是 Google 的专有数据。

两个端点均由志愿者运营。无论 SCRAPER_DELAY_MS 如何设置，Nominatim 每秒一个请求的策略都会在内部强制执行；Overpass 查询会依次尝试多个公共镜像，因为主实例在负载下经常返回 504。

工具输出也受 SCRAPER_MAX_INLINE_CHARS（默认 25,000）限制。超过该值后，结果会被截断，并附上指向 save_as 的提示——因此单次调用不会意外占满你的上下文。

示例提示

Export the whole catalogue from deathwishcoffee.com and tell me the price range.

Find all email addresses on https://company.com and its contact pages.

What platform is https://myblog.com on? Does it need JavaScript to scrape?

Scrape these 200 product pages into a table, then show me everything under £50 that's in stock.

Extract the social media links from these 10 agency sites: [urls...]

配置

所有配置都是环境变量，默认值在未配置时即可正常工作。

将一长串 URL 分批合并到一张表中时，除第一次调用外，每次调用都需要 mode: "append"，否则每一批都会替换掉上一批。渲染后内容稀疏的页面可以传入 wait_ms，或者更好的做法是传入带 CSS 选择器的 wait_for。

行为方式

主内容，而非整页。 文章形态的页面会经过 trafilatura 处理，它会提取正文并去掉周围的装饰性内容——之所以选择它，是因为在一个独立的 2,008 页基准测试中，它的 F1 得分为 0.791，而 Readability 为 0.674。它是逐页应用的，而非全局应用：同一基准测试显示，在产品网格和集合页面上，各提取器的得分相差 20–30 分，因为那里的"主内容"并不是文章，所以列表页保留完整文档。任何页面都可以传入 main_content: false 来强制关闭该处理。

四个层级，仅在被拒绝时逐级升级。 普通 HTTP 客户端能处理大多数页面。如果站点拒绝，请求会使用真实浏览器 TLS 指纹（先是 Chrome，然后是 Safari）重试，因为有些站点会对 TLS 握手本身进行指纹识别，任何请求头改动都无法绕过。js_render: true 会在 Chromium 中渲染以支持单页应用。作为最后手段，经过隐身补丁的浏览器可以处理那些既需要 JavaScript 又 拒绝普通自动化的站点。

每个层级解决不同的失败场景，且没有哪个是其他层级的超集：TLS 层级无法运行 JavaScript，而 Playwright 是可被检测出的自动化浏览器。每次结果都会报告是由哪个层级提供的。设置 SCRAPER_IMPERSONATE=0 或 SCRAPER_STEALTH=0 可以关闭后两个层级，让拦截直接生效。

最后两个层级是规避手段，而非礼貌行为——它们的存在是为了绕过站点有意部署的机器人检测。它们只会在被拒绝后运行，绝不会在站点正常提供页面的情况下触发。

自适应退避。 对同一域名的请求按 SCRAPER_DELAY_MS 间隔，以开始到开始的时间计算，因此延迟限制的是请求速率，而不是在慢响应之上额外叠加。当某个域名出现回推——429、403、Cloudflare 质询——该域名的延迟会翻倍，最高到 60 秒，一旦请求恢复成功便逐渐回落。各域名独立跟踪，因此同时抓取两个站点不会产生额外开销。

不执行 robots.txt。 读取它只是为了定位 sitemap；其中的 Disallow 规则不会被参考，也没有任何设置可以改变这一点。自适应按域名延迟才是本工具的礼貌机制。

短缓存。 抓取到的页面会复用五分钟，因此对同一批 URL 先运行 fetch_pages 再运行 extract_emails 不会重复抓取所有内容。

HTTP 模式

默认是 stdio，也就是上面 claude mcp add 所使用的模式。要改为运行持久化的共享实例：

SCRAPER_AUTH_TOKEN=$(openssl rand -hex 16) cute-web-scraper --http --port 8080

claude mcp add --transport http cute-web-scraper http://127.0.0.1:8080/mcp

它绑定 127.0.0.1，暴露 /mcp 以及一个 /health 端点。绑定到回环地址以外的任何位置都需要 SCRAPER_AUTH_TOKEN，而且服务器在缺少该令牌时会拒绝启动，而不是悄悄向你的网络发布一个开放的抓取器。

限制

• 没有代理轮换，也不解决 CAPTCHA。能扛过全部四个层级的站点会被报告为被拦截，而不是猜测处理。

• LinkedIn 及类似站点可能需要将 SCRAPER_CHROME_USER_DATA_DIR 指向一个已登录的 Chrome 配置文件。

• SCRAPER_DELAY_MS=0 会移除礼貌延迟，但当站点回推时退避机制仍会启动。

• 电话号码提取刻意保守：它要求有国家代码或长途前缀，因此会漏掉一些裸的本地格式，而不是把年份和订单号也当作电话号码返回。

开发

uv sync --extra dev

uv run pytest -v

uv run pytest -m integration -v -s

uv run ruff check src/ tests/ && uv run mypy src/cute_web_scraper/

单元测试是封闭的，绝不访问网络。集成测试会访问真实站点，默认运行中不包含它们。

许可证

MIT——见 LICENSE。