scraperapi-agent-onboarding

ScraperAPI — エージェントのオンボーディング

ScraperAPI を使うと、エージェントやアプリはウェブデータに安定してアクセスできます。任意の URL を、プロキシのローテーション、CAPTCHA の回避、JavaScript のレンダリングを自動処理したうえで、整形済み HTML または Markdown として取得できます。また、20 以上のプラットフォーム（Amazon、Walmart、eBay、Redfin、Google SERP）から構造化 JSON を取得でき、複数ページを抽出するクローラーも利用できます。

このスキルは入り口です。一度読んで進む経路を選び、その経路を担当する、より対象を絞ったスキルに引き継いでください。

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 はキーが間違っているか無効になっていることを示します。同じキーで再試行せず、エラーを報告してください。

---

経路を選択する

状況	経路
LLM エージェントがこのセッション中にウェブデータを必要としている	経路 A — MCP サーバー
アプリのコードに ScraperAPI を追加する	経路 B — SDK／REST 連携
簡単なリクエスト、または Node／Python のない環境	経路 C — REST API を直接利用
まず API キーが必要	経路 D — 認証のみ（上記）

複数の経路にまたがるタスクは、順番に進めてください。キーを取得 → MCP または SDK を設定 → 構築を始める前に実際のリクエストを 1 件テストします。

---

経路 A — MCP サーバー（LLM ツールレイヤー）

利用者が LLM エージェント（Claude Code、カスタムのエージェントループ）で、ScraperAPI をツールとして呼び出す場合に使用します。MCP サーバーは、スクレイピング、Google、Amazon、Walmart、eBay、Redfin、クローラー向けの最大 22 個のツールを、単一の接続で公開します。

リモートサーバー（推奨）

インストールは不要です。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 に対して autoparse: true および outputFormat: "json" を指定して scrape を使用します。

MCP の設定後

scraperapi-mcp スキルに引き継いでください。このスキルでは、22 個すべての MCP ツールについて、ツールの選択、パラメーターの最適化、クレジット費用の案内、エラーからの復旧を扱います。バリアントの判別とトラブルシューティングについては、MCP 設定リファレンスも確認してください。

---

経路 B — SDK／REST 連携（アプリのコード）

コードから ScraperAPI を呼び出すアプリケーション、スクリプト、またはワークフローを構築する場合に使用します。

まずスモークテストを実施する

連携ロジックを書く前に、必ず実際のリクエストを 1 件実行してください。これにより、認証、クレジット、パラメーターの問題をアプリのエラーパスに埋もれる前に検出できます。

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	ドキュメント
JavaScript を多用するページ（React、Vue、SPA）をレンダリングする	標準 API + render=true	ドキュメント
構造化 JSON：Amazon、Google、Walmart、eBay、Redfin	構造化データ API	ドキュメント
一括スクレイピング／100 件以上の URL	非同期ジョブ 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 を指定した生のスクレイピングよりクレジットの消費も少なくなります。