Scrape.ly

scrapely-mcp

一个适用于 Scrape.ly 的 MCP 服务。它让 AI Agent 和 MCP 客户端可以访问 Scrape.ly 账户：在 Store 中搜索 Actors、阅读其 README 和输入架构、运行它们、跟踪运行状态，并读取数据集、键值存储和日志中的结果。它还可以管理已保存的任务，并搜索 Scrape.ly 和 Crawlee 文档。

完整文档：scrape.ly/docs/mcp。

同一个软件包有两种运行方式：

• 托管模式：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,...	将这些 Actors 作为独立工具公开。
--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；随后，Agent 会使用 get-actor-output 获取结果（传入 runId 或 datasetId）。该工具会返回一页数据集项目 （offset、limit，上限为 1000，默认值为 100，以及采用点号表示法的 fields）和运行的 OUTPUT 记录。长文本 值会被截断，且为保持回复精简，每页可能包含少于 limit 个项目；hasMore 和 nextOffset 会指出 后续内容的位置。get-dataset-items 仍可用于更精细的控制。支持协议任务的客户端可以将 call-actor 作为长时间运行的任务执行， 并在运行结束后获取结果。等待运行期间会发送进度通知，取消请求会中止运行。

任何 Scrape.ly API GET 端点也可以通过 resources/read 使用完整 URL 读取，例如 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 issuer 的 API 源站
SCRAPELY_STORE_URL	https://scrape.ly/store	Store 链接的基址
SCRAPELY_STANDBY_BASE_URL	API origin	MCP 服务 Actor 的基址
SCRAPELY_MCP_HOST / SCRAPELY_MCP_PORT	0.0.0.0 / 8000	HTTP 绑定地址
SCRAPELY_ACTORS / SCRAPELY_TOOLS	none	HTTP 服务的默认工具选择
SCRAPELY_MCP_UI / UI_MODE	auto	Widget 模式
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 上限会按 /64 对 IPv6 分组）
SCRAPELY_MCP_MAX_SELECTED_ACTORS	50	单个 ?actors= / ?tools= 选择最多可指定的不同 Actor 数（超过后返回 400）
SCRAPELY_MCP_VALIDATION_BUDGET_SECS	2	验证一次工具调用参数所允许的最长时间；超时的调用会因过大或过于复杂而被拒绝
SCRAPELY_MCP_MAX_REMOTE_RESPONSE_BYTES	10485760	与 MCP 服务 Actor 建立的单个连接可返回的数据字节上限
SCRAPELY_MCP_MAX_REMOTE_TOOL_LIST_BYTES	4194304	与 MCP 服务 Actor 建立的单个 tools/list 连接的数据字节上限
SCRAPELY_MCP_MAX_ACTOR_TOOL_BYTES	1048576	单个 Actor 可添加到会话的工具定义数据量；超过上限的 Actor 会被跳过
SCRAPELY_MCP_MAX_SESSION_TOOL_BYTES	4194304	单个会话可保留的 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	单次工具调用（或任务）可返回的最大结果；超出上限的结果会变为错误
SCRAPELY_MCP_MAX_DATASET_PAGE_BYTES	1048576	存储工具读取的单个数据集页面的字节数；页面会在最后一个完整项之后截断
SCRAPELY_MCP_MAX_RECORD_BYTES	1048576	内联读取的单个键值记录的字节数；较大的记录会以下载链接形式返回
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 Widget（实验性）
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 提供的一两句话，说明用户的需求以及调用该工具的原因。它会在验证参数前被移除，且永远不会传递给工具或 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。