Scrape.ly

scrapely-mcp

Scrape.ly 向けの MCP サーバーです。AI エージェントと MCP クライアントが Scrape.ly アカウントにアクセスし、Store で Actor を検索したり、README と入力スキーマを読み取ったり、実行したり、実行状況を確認したり、データセット、キーと値のストア、ログから結果を読み取ったりできます。また、保存済みタスクの管理や、Scrape.ly および Crawlee のドキュメントの検索もできます。

ドキュメント全文：scrape.ly/docs/mcp。

同じパッケージを 2 通りの方法で実行できます。

• ホステッド：scrapely-mcp-http。マルチテナント対応のストリーミング可能な HTTP サーバーです。Scrape.ly は API の背後でこのサーバーを実行しています（https://mcp.scrape.ly）。ほとんどのユーザーはこの URL に接続するだけで、何もインストールする必要はありません。
• ローカル：scrapely-mcp-server。お使いのマシン上でデスクトップ MCP クライアントが起動する stdio サーバーです。

ホステッドサーバーに接続する

クライアントの接続先として https://mcp.scrape.ly を指定します。

• MCP 認証に対応したクライアントは、自動的に OAuth フローを検出してサインインを求めます。
• それ以外の場合は、API トークンをヘッダーとして送信します：Authorization: Bearer <token>。
• ヘッダーを設定できないクライアントでは、URL に ?token=<token> を追加できます。URL はログに残ることが多いため、ヘッダーを使うことをおすすめします。

JSON 設定を受け取るクライアントの例：

{
  "mcpServers": {
    "scrapely": {
      "url": "https://mcp.scrape.ly",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

ローカルで実行する（stdio）

Python 3.11 以降が必要です。

uvx --from scrapely-mcp scrapely-mcp-server
# or
pip install scrapely-mcp
scrapely-mcp-server

トークンは SCRAPELY_TOKEN から取得されます。それ以外の場合は、~/.scrapely/credentials.json または ~/.scrapely/auth.json の token フィールドから取得されます。選択したすべてのツールがトークンなしで動作する場合（search-actors、fetch-actor-details、およびドキュメントツール）を除き、トークンが必要です。

{
  "mcpServers": {
    "scrapely": {
      "command": "uvx",
      "args": ["--from", "scrapely-mcp", "scrapely-mcp-server"],
      "env": { "SCRAPELY_TOKEN": "YOUR_TOKEN" }
    }
  }
}

オプション：

フラグ	説明
--tools a,b	有効にするツールのカテゴリまたはツール名です。デフォルトのセットを置き換えます。
--actors user/actor,...	これらの Actor を専用のツールとして公開します。
--ui auto|apps|default	MCP Apps のウィジェットモードです（このリリースではウィジェットは無効です。以下を参照してください）。
--telemetry-enabled	使用状況のテレメトリーを有効にします（書き込みキーも必要です。以下を参照してください）。
--telemetry-env PROD|DEV	使用するテレメトリー書き込みキーの環境変数です。

ツール

デフォルトのカテゴリー：actors、docs、runs、storage、tasks、automations。dev カテゴリー（report-problem）はデフォルトで無効です。

カテゴリー	ツール
actors	search-actors、fetch-actor-details、call-actor
docs	search-scrapely-docs、fetch-scrapely-docs
runs	get-actor-run、get-actor-output、get-actor-run-list、get-actor-log、abort-actor-run
storage	get-actor-output、get-dataset、get-dataset-items、get-dataset-schema、get-key-value-store、get-key-value-store-keys、get-key-value-store-record、get-dataset-list、get-key-value-store-list
tasks	create-actor-task、get-actor-task、update-actor-task、publish-actor-task、unpublish-actor-task
automations	list-saved-inputs、run-saved-input、list-automations、run-automation
dev	report-problem

search-scrapely-docs は、デフォルトで scrape.ly/docs の Scrape.ly ドキュメント（docSource: "scrapely"）を検索します。または、Crawlee ドキュメント（crawlee-js、crawlee-py）を検索します。fetch-scrapely-docs はページを Markdown として返します。https://scrape.ly/docs および https://crawlee.dev 配下のページを受け付けます。

call-actor、get-actor-run、または Actor ツールが有効になると、get-actor-run、get-actor-output、get-dataset-items、get-key-value-store-record、abort-actor-run も追加されます。

call-actor は最大 waitSecs（0～45、デフォルトは30）まで待機し、実行ステータスとストレージ ID を返します。その後、エージェントは get-actor-output（runId または datasetId を渡します）で結果を取得します。データセットアイテムのページ（offset、最大1000のlimit（デフォルトは100）、およびドット記法を使用するfields）と、実行のOUTPUTレコードを返します。長いテキスト値は切り詰められ、返信を小さく保つため、ページに含まれるアイテム数がlimitを下回る場合があります。続きの位置はhasMoreとnextOffsetで示されます。より細かく制御する場合は、引き続きget-dataset-itemsを利用できます。プロトコルタスクに対応するクライアントは、長時間実行タスクとしてcall-actorを実行し、実行終了時に結果を取得できます。実行を待機している間は進行状況通知が送信され、リクエストをキャンセルすると実行が中止されます。

Scrape.ly API の任意のGETエンドポイントは、完全な URL を指定してresources/readでも読み取れます。例：https://api.scrape.ly/v2/datasets/<id>/items?limit=20。

ホスト型サーバー

scrapely-mcp-http --host 0.0.0.0 --port 8000

パス	用途
/mcp（およびその他の任意のパス）	MCP エンドポイント（ストリーミング可能な HTTP。ステートレスリクエストも2026-07-28から処理されます）
/.well-known/oauth-protected-resource	OAuth 保護リソースのメタデータ（/mcp サフィックス配下にもあります）
/healthz	ヘルスチェック。{"status":"ok"}

MCP エンドポイントの URL パラメーター：tools、actors、maxActorMemoryBytes、ui、payment（skyfire またはx402）、telemetry-enabled、token。

各セッションには、そのセッションを開始した認証情報の SHA-256 フィンガープリントに紐づく独自のサーバーインスタンスが割り当てられます。異なる認証情報によるリクエストには、そのセッションが存在しない場合と同様に応答します。HTTP サーバーでSCRAPELY_TOKENが使用されることはありません。

コンテナーイメージの定義はDockerfileにあります（docker build --build-arg SOURCE=local -t scrapely-mcp .）。

設定

変数	デフォルト値	用途
SCRAPELY_TOKEN	none	stdio サーバー用のトークン
SCRAPELY_API_BASE_URL	https://api.scrape.ly	外部への呼び出しに使用する API オリジン
SCRAPELY_PUBLIC_API_BASE_URL	derived	クライアントに表示され、OAuth の発行者として使用される API オリジン
SCRAPELY_STORE_URL	https://scrape.ly/store	Store リンクのベース URL
SCRAPELY_STANDBY_BASE_URL	API origin	MCP サーバー Actor のベース URL
SCRAPELY_MCP_HOST / SCRAPELY_MCP_PORT	0.0.0.0 / 8000	HTTP バインドアドレス
SCRAPELY_ACTORS / SCRAPELY_TOOLS	none	HTTP サーバーのデフォルトのツール選択
SCRAPELY_MCP_UI / UI_MODE	auto	ウィジェットモード
SCRAPELY_MCP_SESSION_IDLE_TIMEOUT_SECS	1800	セッションのアイドルタイムアウト
SCRAPELY_MCP_MAX_SESSIONS	10000	セッション上限
SCRAPELY_MCP_MAX_SESSIONS_PER_CREDENTIAL	50	提示されたトークンごとのオープンセッション数。上限を超えると、呼び出し元自身の最も古いアイドルセッションが閉じられるか、リクエストが 429 になります
SCRAPELY_MCP_MAX_SESSIONS_PER_IP	100	クライアント IP ごとのオープンセッション数（API サーバーの /mcp プロキシが設定する、最後の X-Forwarded-For ホップ）
SCRAPELY_MCP_MAX_SESSIONS_PER_IPNET	400	クライアントの IPv6 /48 ごとのオープンセッション数（IP ごとの上限では、IPv6 は /64 単位でグループ化されます）
SCRAPELY_MCP_MAX_SELECTED_ACTORS	50	1 つの ?actors= / ?tools= 選択で指定できる、重複のない Actor の最大数（これを超えると 400）
SCRAPELY_MCP_VALIDATION_BUDGET_SECS	2	1 回のツール呼び出しの引数検証にかけられる時間。これを超える呼び出しは、大きすぎるか複雑すぎるとして拒否されます
SCRAPELY_MCP_MAX_REMOTE_RESPONSE_BYTES	10485760	MCP サーバー Actor への 1 接続が返せるバイト数の上限
SCRAPELY_MCP_MAX_REMOTE_TOOL_LIST_BYTES	4194304	MCP サーバー Actor への 1 回の tools/list 接続で許可されるバイト数の上限
SCRAPELY_MCP_MAX_ACTOR_TOOL_BYTES	1048576	1 つの Actor がセッションに追加できるツール定義のサイズ。上限を超えた Actor はスキップされます
SCRAPELY_MCP_MAX_SESSION_TOOL_BYTES	4194304	1 つのセッションが保持できる Actor ツール定義のサイズ。上限を超えた Actor はスキップされます
SCRAPELY_MCP_MAX_TOTAL_TOOL_BYTES	67108864	すべてのセッションが合計で保持できる Actor ツール定義のサイズ。収まらない新規セッションまたはリクエストは 503 になります
SCRAPELY_MCP_MAX_REMOTE_INFLIGHT_BYTES	67108864	MCP サーバー Actor へのすべてのオープン接続が同時に保持できるバイト数（タスクの結果が保存されるまで）。上限を超えた接続は再試行のヒントとともに失敗します
SCRAPELY_MCP_MAX_TOOL_RESULT_BYTES	4194304	1 回のツール呼び出し（またはタスク）が返せる結果の最大サイズ。これを超えるとエラーになります
SCRAPELY_MCP_MAX_DATASET_PAGE_BYTES	1048576	ストレージツールが読み取る 1 ページのデータセットのバイト数。ページは最後の完全な項目の後で切り詰められます
SCRAPELY_MCP_MAX_RECORD_BYTES	1048576	インラインで読み取る 1 件のキーと値のレコードのバイト数。これを超えるレコードはダウンロードリンクとして返されます
SCRAPELY_MCP_MAX_TASKS_PER_SCOPE	100	セッション／認証情報ごとに保持するプロトコルタスク数。最も古い完了済みタスクから削除されます
SCRAPELY_MCP_MAX_TASKS_TOTAL	10000	合計で保持するプロトコルタスク数
SCRAPELY_MCP_MAX_TASK_RESULT_BYTES_PER_SCOPE	16777216	セッション／認証情報ごとに保持するタスク結果のサイズ。最も古いものから解放されます
SCRAPELY_MCP_MAX_TASK_RESULT_BYTES_TOTAL	134217728	合計で保持するタスク結果のサイズ。最も古いものから解放されます
SCRAPELY_MCP_TASK_RESULT_GRACE_SECS	60	tasks/result がタスク結果を最初に返してから、この時間が経過すると結果が解放されます
SCRAPELY_MCP_TASK_RETENTION_SECS	900	完了済みタスクは、完了後（または ttl の経過後）この時間が経過すると削除されます
SCRAPELY_MCP_REPORT_PROBLEM_BLOCKED_CLIENTS	anthropic,claude	report-problem が表示されないクライアント
SCRAPELY_OFFICIAL_USERNAMES	scrapely	Scrape.ly による保守が表示されるユーザー名。API が maintainedByScrapely フラグを送信しない場合（古い API サーバー）に限ります
SCRAPELY_DOCS_URL	https://scrape.ly/docs	Scrape.ly のドキュメント：search-index.json を通じて検索し、ページは Markdown として読み取ります
SCRAPELY_DOCS_CRAWLEE_JS_*、SCRAPELY_DOCS_CRAWLEE_PY_*	public Crawlee DocSearch values	Crawlee ドキュメントの検索
SCRAPELY_CONSOLE_BASE_URL / SCRAPELY_CONSOLE_TOKEN_PREFIX	disabled	パーソナライズされたダッシュボードリンク
SCRAPELY_MCP_WIDGETS_ENABLED / SCRAPELY_MCP_WIDGET_ASSETS_DIR	off	MCP Apps ウィジェット（実験的）
SCRAPELY_SEND_LEGACY_PAYMENT_HEADER	true	レガシーな決済プロトコルヘッダーも送信します
SKYFIRE_SELLER_SERVICE_ID	none	Skyfire の決済ヒントに表示されます
SCRAPELY_MCP_SESSION_LOG	true	Scrape.ly API に送信されるセッションログ（下記参照）。false にすると無効になります
TELEMETRY_ENABLED、SCRAPELY_TELEMETRY_WRITE_KEY、SCRAPELY_TELEMETRY_ENDPOINT	off	オプトイン方式のテレメトリー
SENTRY_DSN	none	エラー報告（sentry extra をインストールしてください）
LOG_LEVEL	info	ログレベル（ログは stderr に出力されます）
テレメトリーは、有効化され、かつ書き込みキーが設定されている場合を除き、オフです。このパッケージにキーは同梱されていません。ログにトークン、決済トークン、決済署名が含まれることはありません。

セッションログと context パラメーター

すべてのツールは省略可能な context 文字列を受け取ります。これは、ユーザーの希望とツールを呼び出す理由を示す、AI による1～2文の説明です。引数の検証前に削除され、ツールにも Actor にも渡されません。これを送信しないクライアントも、これまでどおり動作します。

サーバーは、独自のトークンを使用して各セッションのアクティビティを Scrape.ly API に報告します。これにより Scrape.ly は、MCP サーバーがどのように使われ、何が失敗するかを確認できます。報告される情報は、クライアント名とバージョン、トランスポート、引数を含む各ツール呼び出し、context、ステータス、所要時間、結果の短い概要です。値はマスキングされず、そのまま送信および保存されるため、Scrape.ly に見られたくない秘密情報をツールの引数に含めないでください。オフにするには、SCRAPELY_MCP_SESSION_LOG=false を設定します。

ウィジェット

MCP Apps のウィジェットツール（search-actors-widget、fetch-actor-details-widget、call-actor-widget、get-actor-run-widget）は実装済みですが、デフォルトでは無効で、ウィジェットの HTML も同梱されていません。ウィジェットが無効の場合、すべてのクライアントには通常のツールセットが提供されます。

開発

uv venv && uv pip install -e ".[test]"
pytest

ライセンス

MIT。詳細は LICENSE をご覧ください。サードパーティーに関する通知は NOTICE に記載されています。