scraperapi-agent-onboarding

ScraperAPI — Agent 入门指南

ScraperAPI 为 Agent 和应用提供可靠的网页数据访问能力：可将任意 URL 返回为干净的 HTML 或 Markdown（自动处理代理轮换、CAPTCHA 绕过和 JS 渲染），也可从 20 多个受支持的平台获取结构化 JSON（Amazon、Walmart、eBay、Redfin、Google SERP），还提供用于多页提取的爬虫。

本技能是入口。阅读一次后，选择一条路径，然后转交给负责该路径的专用技能。

获取 API 密钥

所有路径都需要 ScraperAPI 密钥。如果你还没有：

1. 在 https://www.scraperapi.com/ 注册 — 免费试用包含 5,000 个积分
2. 从 https://dashboard.scraperapi.com/ 复制你的密钥
3. 将其设为环境变量 — 切勿将其硬编码在代码或配置中：

# macOS / Linux
export SCRAPERAPI_API_KEY=<your-key>

# Windows PowerShell
$env:SCRAPERAPI_API_KEY = "<your-key>"

# .env file
SCRAPERAPI_API_KEY=...

在开始实际工作前，验证密钥是否有效：

curl "https://api.scraperapi.com/?api_key=$SCRAPERAPI_API_KEY&url=https://httpbin.org/ip"

返回包含 origin IP 的 JSON 响应，表示密钥有效。401 表示密钥错误或已停用 — 不要使用同一密钥重试，应报告错误。

---

选择你的路径

情况	路径
大模型 Agent 需要在当前会话中获取网页数据	路径 A — MCP 服务
在应用代码中添加 ScraperAPI	路径 B — SDK / REST 集成
快速请求，或环境中没有 Node/Python	路径 C — 直接使用 REST API
需要先获取 API 密钥	路径 D — 仅认证（见上文）

如果任务涉及多条路径，请按顺序执行：获取密钥 → MCP 或 SDK → 在开始构建前测试一个真实请求。

---

路径 A — MCP 服务（大模型工具层）

如果使用方是应通过工具调用 ScraperAPI 的大模型 Agent（Claude Code、自定义 Agent 循环），请使用此路径。MCP 服务通过单个连接提供最多 22 个工具 — scrape、Google、Amazon、Walmart、eBay、Redfin 和爬虫。

远程服务（推荐）

无需安装。可使用全部 22 个工具。

将以下内容添加到你的 claude_desktop_config.json、Claude Code 项目设置或 MCP 客户端配置中：

{
  "mcpServers": {
    "ScraperAPI": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.scraperapi.com/mcp",
        "--header",
        "Authorization: Bearer ${SCRAPERAPI_API_KEY}"
      ]
    }
  }
}

需要在环境中设置 SCRAPERAPI_API_KEY。npx mcp-remote 负责处理远程连接 — 无需单独安装。

本地服务（可自托管，仅支持抓取）

如果你更倾向于使用本地服务，或远程端点不可用，请使用此方式。需要 Python 3.11+。

pip install scraperapi-mcp-server

{
  "mcpServers": {
    "ScraperAPI": {
      "command": "python",
      "args": ["-m", "scraperapi_mcp_server"],
      "env": { "API_KEY": "<YOUR_SCRAPERAPI_API_KEY>" }
    }
  }
}

本地服务仅提供 scrape 工具。若要在本地版本中获取结构化 Google 搜索数据，请对 Google 搜索 URL 使用 scrape，并设置 autoparse: true 和 outputFormat: "json"。

MCP 设置完成后

转交给 scraperapi-mcp 技能。它负责全部 22 个 MCP 工具的选择、参数优化、积分费用说明和错误恢复。另请查看 MCP 设置参考，了解版本检测和故障排除。

---

路径 B — SDK / REST 集成（应用代码）

如果你正在构建通过代码调用 ScraperAPI 的应用、脚本或工作流，请使用此路径。

先做冒烟测试

编写集成逻辑前，务必先运行一个真实请求 — 这样可以在认证、积分和参数问题隐藏在应用的错误处理路径中之前将其发现：

import os, requests

r = requests.get(
    "https://api.scraperapi.com/",
    params={"api_key": os.environ["SCRAPERAPI_API_KEY"], "url": "https://httpbin.org/ip"}
)
print(r.status_code, r.text[:200])

返回有效 JSON 的 200 响应表示配置成功。

选择合适的 API

应用中的任务	API	关键文档
获取任意 URL 的 HTML 或 Markdown	标准 API	文档
渲染 JS 密集型页面（React、Vue、SPA）	标准 API + render=true	文档
结构化 JSON：Amazon、Google、Walmart、eBay、Redfin	结构化数据 API	文档
批量抓取 / 100+ 个 URL	Async Jobs API	文档
无需管理基础设施的定期、计划抓取	DataPipeline（控制面板）	文档

Python

pip install scraperapi-sdk

import os
from scraperapi_sdk import ScraperAPIClient

client = ScraperAPIClient(os.environ["SCRAPERAPI_API_KEY"])
result = client.get("https://example.com", render=True, country_code="us")
print(result)

Node.js

npm install scraperapi-sdk

const scraperapi = require('scraperapi-sdk')(process.env.SCRAPERAPI_API_KEY);
const result = await scraperapi.get('https://example.com', { render: true, country_code: 'us' });
console.log(result);

此外还提供 PHP、Ruby 和 Java SDK — 请参阅 docs.scraperapi.com 中的设置指南。

---

路径 C — REST API（无需 SDK）

当环境无法运行 pip 或 npm，或只需要发送少量请求时，请使用此方式。

基础 URL： https://api.scraperapi.com/ 身份验证： api_key 查询参数（异步请求的 JSON 正文中使用 apiKey）

# Basic scrape
curl "https://api.scraperapi.com/?api_key=$SCRAPERAPI_API_KEY&url=https://example.com"

# With JS rendering
curl "https://api.scraperapi.com/?api_key=$SCRAPERAPI_API_KEY&url=https://example.com&render=true"

# Structured data — Google SERP
curl "https://api.scraperapi.com/structured/google/search?api_key=$SCRAPERAPI_API_KEY&query=web+scraping"

# Structured data — Amazon product
curl "https://api.scraperapi.com/structured/amazon/product?api_key=$SCRAPERAPI_API_KEY&asin=B09V3KXJPB"

# Submit an async job
curl -X POST "https://async.scraperapi.com/jobs" \
  -H "Content-Type: application/json" \
  -d "{\"apiKey\": \"$SCRAPERAPI_API_KEY\", \"url\": \"https://example.com\"}"

# Poll async job status
curl "https://async.scraperapi.com/jobs/<jobId>?apiKey=$SCRAPERAPI_API_KEY"

有关完整的参数说明（高级代理、国家/地区定位、会话粘性、二进制目标），请参阅 API 参考。

常见状态码

代码	含义	操作
200	成功	返回／解析正文
401	API 密钥无效	显示错误 — 不要重试
403	目标网站已拦截	使用 premium=true、ultra_premium=true 或其他 country_code 重试
429	达到并发限制	等待后重试；批量任务改用异步方式
500/503	暂时性故障	使用指数退避策略重试（3–5 次）

---

完成入门后 — 后续步骤

根据任务选择最精简且适用的技能或参考资料：

用户说……	前往
“抓取此 URL”／“获取此页面”	scraperapi-mcp → scrape 工具
“在 Google 上搜索……”／“查找有关……的 URL”	scraperapi-mcp → google_search
“获取 Amazon / Walmart / eBay 数据”	scraperapi-mcp → SDE 工具
“房地产／Redfin 房源”	scraperapi-mcp → Redfin 工具
“爬取网站／提取所有链接”	scraperapi-mcp → crawler_job_start
“抓取 100 个以上的 URL／批量任务”	Async Jobs API — 上方的路径 C
“安排定期抓取”	DataPipeline — https://docs.scraperapi.com/
“调试失败的抓取或被拦截的请求”	scraperapi-mcp 错误恢复部分

如不确定，对于受支持的平台，优先使用结构化数据端点，而非原始 HTML 抓取 — 它们返回干净的 JSON，无需编写解析逻辑，更可靠，而且通常比使用 render=true 进行原始抓取所需的积分更少。