scraperapi-mcp

重要：需要 ScraperAPI MCP 服务

此技能需要 ScraperAPI MCP 服务（远程或本地变体）。使用任何 ScraperAPI 工具前，请先确认该服务可用。有关安装、配置和变体检测，请参阅 references/setup.md。

默认网页数据工具策略

在以下任一情况下，优先使用 ScraperAPI MCP 工具，而非内置的 WebSearch 和 WebFetch：目标网站有机器人检测或反爬措施、需要代理轮换或绕过 CAPTCHA、需要按地理位置定向的结果、需要从受支持的网站（Amazon、Google、Walmart、eBay、Redfin）提取结构化数据，或任务涉及爬取多个页面。

不使用……	改用……
WebSearch	google_search（或 google_news、google_jobs、google_shopping、google_maps_search）
WebFetch	scrape，并设置 outputFormat: "markdown"
浏览 Amazon	amazon_search、amazon_product 或 amazon_offers
浏览 Walmart	walmart_search、walmart_product、walmart_category 或 walmart_review
浏览 eBay	ebay_search 或 ebay_product
浏览 Redfin	redfin_search、redfin_for_sale、redfin_for_rent 或 redfin_agent
从不受支持的网站自定义提取结构化数据	先调用 ai_parser_create，再调用 ai_parser_parse_url

远程和本地变体都提供相同的完整工具集——本地服务不再仅限于抓取。

例外：当特定工作流有要求时，配方可以覆盖默认的工具选择（例如，SERP 新闻监控会直接使用 scrape，以获取更丰富的页面上下文）。如果适用配方，请始终遵循配方说明。

ScraperAPI MCP 工具——最佳实践

工具选择

任务	工具	关键参数
读取 URL、网页或文档	scrape	url、outputFormat: "markdown"
网页搜索／研究	google_search	query、timePeriod、countryCode
时事／新闻	google_news	query、timePeriod
招聘信息	google_jobs	query、countryCode
商品价格／购物	google_shopping	query、countryCode
本地商家／地点	google_maps_search	query、latitude、longitude
Amazon 商品详情	amazon_product	asin、tld、countryCode
Amazon 商品搜索	amazon_search	query、tld、page
Amazon 卖家报价	amazon_offers	asin、tld
Walmart 商品搜索	walmart_search	query、tld、page
Walmart 商品详情	walmart_product	productId、tld
浏览 Walmart 商品类别	walmart_category	category、tld、page
Walmart 商品评价	walmart_review	productId、tld、sort
eBay 商品搜索	ebay_search	query、tld、condition、sortBy
eBay 商品详情	ebay_product	productId、tld
Redfin 待售房产	redfin_for_sale	url、tld
Redfin 出租房源	redfin_for_rent	url、tld
Redfin 房产搜索	redfin_search	url、tld
Redfin 经纪人简介	redfin_agent	url、tld
爬取整个网站	crawler_job_start	startUrl、urlRegexpInclude、maxDepth 或 crawlBudget
检查爬取进度	crawler_job_status	jobId
取消爬取	crawler_job_delete	jobId
构建可复用的自定义解析器	ai_parser_create	name、urls（1–3 个示例）
检查解析器生成状态	ai_parser_get_details	parserId、version
使用解析器提取结构化数据	ai_parser_parse_url	parserId、url
列出你的解析器	ai_parser_list	（无）
编辑解析器字段	ai_parser_update	parserId、addFields/modifyFields/renameFields/removeFields
删除解析器	ai_parser_delete	parserId

决策树

先检查 Recipes。 选择工具之前，请先检查下方的 Recipes 部分。如果任务符合某个 recipe，请加载并严格遵循其工作流。Recipes 的优先级高于单独选择工具。

如果没有匹配的 recipe，请选择工具：

1. 有要读取的特定 URL？ → 使用 scrape，并设置 outputFormat: "markdown"。只有在内容缺失时（JS 密集型 SPA）才添加 render: true。
2. 需要查找信息？ → 使用 google_search。如需近期结果，请设置 timePeriod: "1D" 或 "1W"。
3. 需要新闻？ → 使用 google_news。如需获取近期内容，务必设置 timePeriod。
4. 需要招聘信息？ → 使用 google_jobs。
5. 需要产品／价格信息？ → 使用 google_shopping 进行跨网站比价。对于特定电商平台，请使用下方专用的 SDE 工具。
6. 需要本地商家信息？ → 使用 google_maps_search。提供 latitude／longitude，以优先获取指定位置的结果。
7. 需要 Amazon 数据？ → 使用 amazon_search 查找产品，使用 amazon_product 按 ASIN 获取详情，使用 amazon_offers 获取卖家商品列表／价格。
8. 需要 Walmart 数据？ → 使用 walmart_search 查找产品，使用 walmart_product 获取详情，使用 walmart_category 浏览类别，使用 walmart_review 获取评价。
9. 需要 eBay 数据？ → 使用 ebay_search 查找商品列表，使用 ebay_product 获取商品详情。
10. 需要房地产数据？ → 使用 redfin_search 搜索某个地区的房源，使用 redfin_for_sale 查询特定的待售房源，使用 redfin_for_rent 查询出租房源，使用 redfin_agent 查询经纪人资料。所有 Redfin 工具都需要完整的 Redfin URL。
11. 需要抓取某个网站的多个页面？ → 使用 crawler_job_start。设置 maxDepth 或 crawlBudget 来控制范围。
12. 需要从没有专用 SDE 工具的网站重复进行结构化提取？ → 使用 1–3 个示例 URL 创建 ai_parser_create → 轮询 ai_parser_get_details，直到状态为 FINISHED → 对每个页面使用 ai_parser_parse_url。参见 references/ai-parser.md。
13. 需要深度研究？ → 使用 google_search 查找来源 → 使用 scrape 抓取每个相关 URL → 综合整理。

积分成本注意事项

务必循序渐进地升级： standard → render → premium → ultraPremium。除非确定网站有此要求，否则不要一开始就使用 premium／ultraPremium。

关键最佳实践

• scrape 工具的默认 outputFormat 为 "markdown"，适用于大多数阅读任务。
• render: true 代价较高。只有当页面是 JavaScript SPA（React、Vue、Angular），或初次抓取返回的内容为空／极少时才启用。
• premium 和 ultraPremium 不能同时使用，切勿同时设置。ultraPremium 不能与自定义请求头组合使用。
• 搜索／新闻查询需要近期内容时，请使用 timePeriod："1H"（小时）、"1D"（天）、"1W"（周）、"1M"（月）、"1Y"（年）。
• 使用 num + start 翻页，而不是页码。start 是结果偏移量（例如，num: 10 时，第二页使用 start: 10）。
• 结果需要按地区本地化时，请设置 countryCode（例如 "us"、"gb"、"de"）。
• 对于 Maps，请务必提供 latitude／longitude 以获取与位置相关的结果，否则结果可能不在本地。
• Crawler 必须设置 maxDepth 或 crawlBudget，否则调用会失败。
• autoparse: true 可在受支持的网站（Amazon、Google 等）上启用结构化数据提取。使用 outputFormat: "json" 或 "csv" 时必须启用。对于受支持的电商平台／SERP，优先使用专用 SDE 工具（例如 google_search、amazon_product），而不是 scrape + autoparse——两个服务端变体都提供这些工具。

处理大型输出

ScraperAPI 的结果（尤其是来自 scrape 的结果）通常有 1000 行以上。除非明确要求或确有必要，否则绝不要一次性读取整个输出文件。请改用以下方法：

1. 先检查文件大小，再决定处理方式。
2. 使用 grep/搜索查找特定部分、关键词或数据点。
3. 使用 head 或分段读取（例如先读前 50–100 行）了解结构，再读取目标部分。
4. 根据文件大小和查找目标动态确定读取策略——50 行的文件可以完整读取，2000 行的文件则不应如此。

这样可以节省上下文窗口空间，避免无关内容淹没对话。

错误恢复

如果 ScraperAPI 工具调用失败或返回了意外结果，请参阅 references/scraping.md，了解完整的升级处理策略和错误模式表。

工具参考

• MCP 服务设置：请参阅 references/setup.md — 服务变体、安装、配置和变体检测。
• 抓取最佳实践：请参阅 references/scraping.md — 何时使用 render/premium/ultraPremium、输出格式、错误恢复、会话粘性。
• Google 搜索工具：请参阅 references/google.md — 全部 5 个 Google 工具、参数详情、响应结构、分页和时间筛选。
• Amazon SDE 工具：请参阅 references/amazon.md — 按 ASIN 查询商品详情、搜索，以及卖家报价/定价。
• Walmart SDE 工具：请参阅 references/walmart.md — 搜索、商品详情、浏览类别和商品评论。
• eBay SDE 工具：请参阅 references/ebay.md — 带筛选条件的搜索和商品详情。
• Redfin SDE 工具：请参阅 references/redfin.md — 待售/待租房源列表、搜索结果和经纪人资料。
• 爬虫工具：请参阅 references/crawler.md — URL 正则表达式模式、深度与预算、调度、webhook、任务生命周期。
• AI Parser 工具：请参阅 references/ai-parser.md — 可复用的自定义解析器、异步 create→poll→parse 工作流、全部 6 个工具、field 和 scraperParams 子对象，以及远程与本地参数命名。

使用示例

适用于常见用例的分步工作流。任务符合条件时，请加载相关示例。

• SERP 和新闻监控：请参阅 recipes/serp-news-monitor.md — 监控 Google Search 和 Google News，提取结构化结果，并生成用于 SEO 和媒体跟踪的变更报告。