ZenRows MCP

Zenrows MCP 服务

Zenrows MCP（Model Context Protocol）服务是 AI 系统使用 Zenrows 网络数据基础设施的标准方式。只需建立一个连接，您的 AI 助手、Agent 或应用程序即可可靠、实时地访问实时网络，包括受保护的网站。

📚 完整文档： docs.zenrows.com/mcp/overview

---

为什么选择 Zenrows MCP

• 访问通常会屏蔽机器人的网站。 大规模可靠地访问受保护的网站，无需自行构建反机器人处理机制。
• 托管式网络数据基础设施。 代理轮换、无头浏览器编排、反机器人处理和会话管理均在 Zenrows 的基础设施上运行。
• 接入您已在使用的任意 AI。 兼容任何 MCP 客户端，包括 AI 助手、Agent 框架、AI SDK、IDE 插件和自定义应用程序。
• 使用日常语言，无需编写抓取代码。 自然地描述任务，AI 就会选择合适的工具。无需选择器、代理管理或反机器人调优。

---

快速开始

Zenrows MCP 支持两种传输方式。两者提供相同的工具集和功能。请选择适合您客户端的方式。

无需密钥即可使用的功能：

• 本地（npx @zenrows/mcp）： 无需注册或密钥。首次调用工具时会创建一个免费账户（每月 5,000 个点数），您之后可以认领该账户，并保留密钥及其使用记录。使用 ZENROWS_AUTO_SIGNUP=false 选择退出。在 CI 中，将 ZENROWS_API_KEY 设为密钥，或在多次运行之间保留 ZENROWS_HOME。
• 远程（https://mcp.zenrows.com/mcp）： initialize 和 tools/list 无需密钥即可响应；调用工具则需要密钥（支持 OAuth 的客户端可使用 OAuth，也可使用 Bearer 密钥）。远程服务不会自行创建账户。无头 Agent 可通过 POST https://app.zenrows.com/api/agent/signup 创建免费账户，并将返回的 apiKey 用作 Bearer 令牌。该端点可能会先返回带有简短问题的 428；将 {"challenge_id": "...", "answer": "..."} POST 回同一 URL 即可获取密钥。

远程 MCP 服务

当您的 AI 应用直接调用 LLM API 时，请使用托管的 Zenrows MCP 服务。该服务运行在 Zenrows 的基础设施上，因此无需安装、配置或更新。

服务 URL：

https://mcp.zenrows.com/mcp

传输方式： Streamable HTTP

身份验证： OAuth 或作为 Bearer 令牌的 API 密钥。请在每个请求的 Authorization 标头中传递 Zenrows API 密钥（或在支持 OAuth 的客户端中完成 OAuth）。

Authorization: Bearer YOUR_ZENROWS_API_KEY

大多数 MCP 客户端都支持在工具配置中使用 authorization 简写字段，并会自动将其作为 Bearer 令牌转发。有些客户端则使用自由格式的 headers 字段。两种方式均可使用。

远程 MCP 不会自动创建账户。无需密钥即可使用 initialize 和 tools/list；不带密钥调用工具会返回 401，响应正文中会指出注册端点（agent_signup）。您可以在客户端中通过 OAuth 选择“创建免费账户”，传入现有 API 密钥，或者从无头 Agent 调用 POST https://app.zenrows.com/api/agent/signup（匿名；返回 apiKey，也可能先返回一个 428 问题，需使用 challenge_id 和 answer 作答；受网络级别的速率限制），然后使用 Authorization: Bearer <apiKey> 重试。

示例：OpenAI Responses API

import os
from openai import OpenAI

ZENROWS_API_KEY = os.environ["ZENROWS_API_KEY"]
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.responses.create(
    model="gpt-5",
    tools=[
        {
            "type": "mcp",
            "server_label": "zenrows",
            "server_description": "Web scraping MCP server for accessing live web content.",
            "server_url": "https://mcp.zenrows.com/mcp",
            "authorization": ZENROWS_API_KEY,
            "require_approval": "never",
        }
    ],
    input="Visit https://news.ycombinator.com/ and summarize the three most recent posts.",
)

print(response.output_text)

如需查看包含框架专属示例的完整指南，请参阅远程 MCP 服务文档。

本地 MCP 服务

当 MCP 客户端将服务作为本地子进程运行，而不是调用远程 URL 时，请使用本地 stdio 配置。这是桌面 AI 工具和 IDE 插件的标准设置，包括 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code、Zed 和 JetBrains IDE。

软件包： npm 上的 @zenrows/mcp

身份验证：

1. ZENROWS_API_KEY 环境变量，或
2. 之前存储在 ~/.zenrows/secrets.json 中的密钥，或
3. 自动注册（默认）：如果两者都未设置，服务仍会启动，并在首次工具调用时通过 POST /api/agent/signup 为你开通 Free 计划账户，将密钥和认领元数据保存到 ~/.zenrows/ 下（secrets.json + account.json，模式为 0600），并在 stderr 上打印认领 URL。Zenrows 可能会先提出一个简短问题：此时工具调用会返回该问题，Agent 随后使用 account_signup_answer 工具作答，然后重试。如果注册被拒绝（例如在 CI 中触及每个网络的上限），该工具调用会返回错误并说明何时可以重试；在 CI 中，请将 ZENROWS_API_KEY 设为密钥，或在运行之间保留 ZENROWS_HOME。设置 ZENROWS_AUTO_SIGNUP=false 可退出自动注册：设置密钥之前，工具调用都会返回错误。注册请求还会发送一个每台机器随机生成的 ID（与 Zenrows CLI 共享），以及对宿主 Agent 的推测（claude-code、cursor 等），以便归属注册来源；设置 ZENROWS_TELEMETRY=off 可省略这两项。

**要求：**已安装 Node.js（以便 npx 正常运行）。

配置（使用你自己的密钥）：

{
  "mcpServers": {
    "zenrows": {
      "command": "npx",
      "args": ["-y", "@zenrows/mcp"],
      "env": {
        "ZENROWS_API_KEY": "YOUR_ZENROWS_API_KEY"
      }
    }
  }
}

零配置（自动注册）：

{
  "mcpServers": {
    "zenrows": {
      "command": "npx",
      "args": ["-y", "@zenrows/mcp"]
    }
  }
}

可选：ZENROWS_CRAWL_API_BASE 为 crawl_* 工具设置 Crawl API 基础 URL（默认为 https://api.zenrows.com/v1）。仅当需要将这些工具指向其他部署时才设置。

可选：ZENROWS_BATCH_API_BASE 为 batch_* 工具设置 Batch API 基础 URL（默认为 https://async.api.zenrows.com/v1）。仅当需要将这些工具指向其他部署时才设置。

此配置的具体位置因客户端而异。请参阅各客户端设置指南，了解你的客户端对应的文件路径。

---

工具

Zenrows MCP 提供以下工具系列：

工具	用途
scrape	将完整页面内容转换为 Markdown、纯文本、HTML、PDF 或截图（以及辅助输出）。
extract	结构化 JSON（extract=auto 或 css_extractor；autoparse 已弃用）+ 可选的隐身标记。extract=auto 目前免费（以后可能收费），适用于任何已准备的域名，且可使用任意 API 密钥。仅返回 parsed 字段；设置 include_html: true 还可获取页面 HTML。错误 REQS007 会在 reason 中说明原因：domain_not_prepared → 调用 prepare_domain（错误中包含其参数；一个 URL 即可；我们建议提供 3 个或更多相同页面类型的 URL，因此请将它们添加到 example_urls，最多 5 个）；page_not_recognised → 域名已准备好，但此页面不是 Extract 会提取内容的页面（例如没有可提取内容的主页）：请改试产品页、文章页或列表页；如果页面本应可用，请几分钟后重试一次，否则请使用 css_extractor，且不要再次准备；domain_not_enabled → 准备域名没有帮助，请使用 css_extractor。错误不会建议使用 autoparse，工具也绝不会回退到它：fallback_autoparse 已弃用且不起作用（值为 true 时，结果中会包含说明其已被忽略的 note）。
prepare_domain / prepared_domain_status	在 REQS007 的原因是 domain_not_prepared 时，为 extract（mode=auto）准备域名。prepare_domain 接受域名和 1 至 5 个示例 URL。一个即可；我们建议提供 3 个或更多相同页面类型的 URL（例如 3 个产品页：https://www.example.com/products/a、/products/b 和 /products/c），因为 Extract 会比较同一类型的页面，以检查找到的字段并补全某个页面缺失的字段。多个页面类型可共用 5 个名额（例如 3 个产品页 + 2 个搜索结果页）。它会立即返回 status: "preparing"（不会等待），且不消耗额度。准备需要几分钟：大约每 30 秒轮询一次 prepared_domain_status（状态、当前步骤、失败代码、账户每月额度的 used / limit / remaining，以及当前应执行步骤 next），直到 status 为 ready，然后再次调用 extract。每个新域名占用一个额度名额；已准备好的域名会立即返回 ready，并带有 already_prepared: true，且不占用额度。域名指主机名：shop.example.com 和 example.com 分别准备，开头的 www. 会被移除。
batch_create / batch_status / batch_wait / batch_results / batch_content / batch_list / batch_cancel / batch_pause / batch_resume / batch_rerun / batch_delete	云端 Batch API 扇出（async.api.zenrows.com）。与 Fetch 消耗相同额度。不是 browser_batch。请参阅下文的 Batch 工具。
crawl_create / crawl_get / crawl_results / crawl_content / crawl_download / crawl_list / crawl_stop / crawl_wait	Crawl API（api.zenrows.com/v1/crawls）。新功能。Crawl 仍在不断完善：新功能即将推出，限制可能调整，变更会在更新日志中逐一公布。提供一个起始 URL，即可获取其背后位于同一可注册域名下的 URL（子域名也算），还可选择获取每个页面的 HTML（output_format: "html"）。crawl_create 会立即返回；调用 crawl_wait（返回计数和前 20 个 URL），然后调用 crawl_download 将所有结果保存到本地 JSON Lines 文件（默认路径为 ~/.zenrows/crawls/<crawl_id>.jsonl；path 必须位于 ~/.zenrows/crawls 内；除非设置 overwrite: true，否则会保留已有文件；托管服务端不会写入文件，而是返回下载 URL 和 curl 命令），也可以调用 crawl_results 分页查看结果。若在 crawl_create 中省略 depth，则不设深度限制：爬取会持续跟踪链接，直到 max_pages 或 max_items（每项默认值均为 100）达到上限；每个抓取的页面按一次 scrape 计费。在 crawl_create 中设置 idempotency_key，以确保重试安全。crawl_content 接受 crawl_id 和 content_id（内容 ID 或结果的 content_url）。读取操作遇到 429、502、503、504 和网络错误时会重试（最多 3 次，并遵循最长 30 秒的 Retry-After）；crawl_create 仅在设置了 idempotency_key 时重试，且绝不会在遇到 429 时重试；crawl_stop 遇到 429、502、503 和 504 时会重试（重复停止是安全的；503 crawl_busy 表示停止操作尚未保存），最多重试 3 次，总时长不超过 50 秒；如果 crawl_busy 持续出现，则返回 CRAWL_BUSY。可能返回 CRAWL_NOT_ENABLED（此账户未启用 Crawl）。
browser_*	30 多种工具，用于完整的浏览器自动化（导航、点击、表单、JS、Cookie、标签页、会话）。

批量工具

批量任务会异步抓取多个 URL。常见流程：先调用 batch_create，然后调用 batch_wait 等待运行结束，再调用 batch_results 分页读取各行，最后调用 batch_content 读取某个任务的页面。

• batch_create 提交一个包含所有任务的完整批量任务，每次调用最多 100,000 个任务。每个任务都需要一个 url（http 或 https，最多 2,048 个字符），还可选择提供 external_id（最多 128 个字符，可包含字母、数字、.、_ 和 -；不必唯一）、metadata（最多 20 个键值均为字符串的条目，总计 4 KiB）、POST 任务所需的 method 和 body（body 最多 16 KiB；POST 仅用于只读查询，因为目标端可能会多次收到 POST），以及抓取参数（可放在 zenrows_params 中，也可直接放在任务对象中）。未知任务字段会在发送任何内容之前按名称导致调用失败。response_type 可设为 markdown、plaintext 或 pdf；省略时使用 HTML。任务默认使用 mode=auto，除非你强制指定 js_render 或 premium_proxy。每次调用都会发送一个 Idempotency-Key；除非你设置 idempotency_key，否则该键会自动生成：24 小时内，使用相同键和请求正文重试会返回原任务，而不是创建第二个任务；使用不同正文则会返回 BATCH_IDEMPOTENCY_CONFLICT。错误回复中会附带可用于重试的键。设置 wait: true 后，调用会在运行结束或暂停时返回；若 wait_timeout（秒，默认值为 50）到期，也会返回。
• batch_status 和 batch_wait 会报告最新一次运行的 status（pending、running、completed、stopped、failed）和 stats。batch_wait 会轮询直到运行结束；若运行已暂停，则立即返回并带有 paused: true，且能够容忍暂时性错误。其 timeout 以秒为单位（默认值为 50，低于许多客户端会取消调用的 60 秒）；超时后，回复会包含当前状态，并带有 ok: true、timed_out: true 和一条说明，而非错误。带有 progressToken 的调用会在每次轮询后收到进度通知。若运行仍在写入任务（提交数量达到或超过 10,000，以及每次重新运行时），则会包含 ingesting: true。
• batch_results 最多返回 limit 行（默认值为 100，最大值为 1,000）和一个 next_cursor；将其作为 cursor 传回，直到其值为 null。使用 status 筛选：all、successful、failed 或 processing。对于较早的运行，请传入 run_id。某行的 result_url 是有效期为 2 小时的预签名 URL；若要获取新的 URL，请再次列出结果，或使用 batch_content。结果默认保留 14 天；此后，成功行的状态会显示为 expired，且不再包含 result_url。
• batch_content 返回某个任务的结果。文本（HTML、Markdown、纯文本、JSON）会直接内嵌返回，并截断至 max_chars（默认值为 20,000）；PDF 则通过预签名的 result_url 返回。对于大型批量任务，可能需要多次调用才能找到结果，届时回复会包含 lookup_cursor，供后续调用传回。尚未完成的任务会返回 BATCH_TASK_NOT_READY，失败的任务会返回 BATCH_TASK_FAILED（并包含 task_error），已过期的任务会返回 BATCH_RESULT_EXPIRED。
• batch_list 按创建时间从新到旧列出该账户的批量任务（每页默认 20 个，最多 100 个）。
• batch_cancel 会永久停止当前运行：等待中的任务不会启动，正在执行的任务会完成并计费，结果会保留。batch_pause 会暂停运行，直到调用 batch_resume；暂停的运行仍会计为活动任务。这三种操作都是幂等的；如果运行已经结束，则会返回其最终状态并带有 already_ended: true。
• batch_rerun 会在最近一次运行结束后启动新一轮运行。默认情况下，它会重新运行 failed 和 pending 任务，并沿用其他任务的结果：可用于恢复因积分耗尽或任务取消而中断的运行。传入 status 可指定其他任务状态，或传入 full: true 重新抓取所有任务。运行开始后 10 天内可进行部分重新运行。此操作会发送 Idempotency-Key。
• batch_delete 会删除批量任务及其所有运行和结果，并释放其活动任务名额。 费用：与常规 API 使用相同的额度，按成功任务计费：基础模式为 1 点，使用 js_render 为 5 点，使用 premium_proxy 为 10 点，两者都使用为 25 点；mode=auto 会按任务成功时使用的配置计费。失败任务不计费，但目标返回 404 和 410 的情况除外。账户默认可同时运行 3 个活动作业，与 Crawl 共用上限。

以 failed 结束的运行会返回 ok: false，其中 error.code 与对应的 HTTP 错误相同（订阅未激活时为 BATCH_INSUFFICIENT_CREDITS、BATCH_KEY_CAP_REACHED 或 AUTH_INVALID；其他情况为 BATCH_RUN_FAILED），error.server_code（即 failure_reason）、error.job_id 和处理建议。修复原因后，调用 batch_rerun。

错误包含 code、message、detail、server_code（Batch API 自身的代码），以及在针对单个作业的调用中包含的 job_id：

代码	情况
BATCH_INVALID_REQUEST	400：请求遭到拒绝；invalid_tasks 列出首批错误任务。未创建任何内容。
AUTH_INVALID	401：API 密钥遭到拒绝；或者当 server_code 为 subscription_inactive 时，密钥有效，但需要在 Billing 中修复订阅。
BATCH_INSUFFICIENT_CREDITS	402：账户已无剩余额度。
BATCH_KEY_CAP_REACHED	402：此 API 密钥已达到某项额度上限；账户的其他密钥仍可使用。
BATCH_ACCESS_DENIED	403：此账户或密钥未启用 Batch。请勿重试。
BATCH_NOT_FOUND	404：此账户不存在该作业、运行或任务（包括已删除的作业）。
BATCH_RUN_ENDED、BATCH_RUN_NOT_FINISHED、BATCH_NO_MATCHING_TASKS、BATCH_RERUN_WINDOW_EXPIRED、BATCH_NO_PRIOR_RUN、BATCH_IDEMPOTENCY_CONFLICT、BATCH_TASK_NOT_READY、BATCH_CONFLICT	409，具体情况由 server_code 指明。
BATCH_RESULT_EXPIRED	410：已超过作业的保留期限。
BATCH_TASK_FAILED	422：任务失败；其错误存于 task_error。
BATCH_QUOTA_EXCEEDED	429：超出作业数量上限，增加额度也无法提高上限（3 个活动作业，与 Crawl 共用；5 个计划作业）。
BATCH_RATE_LIMITED	其他任何 429。
BATCH_FAILED	其他任何 HTTP 错误。
BACKEND_UNAVAILABLE	无响应：重试后仍发生网络错误或超时。

读取请求在遇到 429、500、502、503、504 和网络错误时会重试，最多重试 3 次，并遵循最长 30 秒的 Retry-After。batch_create 和 batch_rerun 在遇到 500、502、503、504、网络错误以及带有 Retry-After 的 429 时会重试，且始终使用相同的 Idempotency-Key；作业数量上限导致的 429 不会重试。对于同一请求出现的 BATCH_IDEMPOTENCY_CONFLICT，请保留该密钥，检查 batch_list 并稍后重试：使用新密钥可能会创建第二个需要计费的作业。

计划、webhook、结果导出、CSV 输入、开放作业（随时间添加任务）、运行和任务历史记录，仅可通过 Batch API 和 Zenrows SDK 获取。

AI 会根据你的提示词选择合适的工具。你无需在代码中直接调用工具。

请参阅完整工具参考，了解所有工具、参数和返回值。

---

开发

git clone https://github.com/ZenRows/zenrows-mcp
cd zenrows-mcp
npm install
cp .env.example .env   # Optional: add your API key (stdio can auto-signup)
npm run dev            # Run with .env loaded (requires Node.js 20.6+)
npm run build          # Compile to dist/
npm run inspect        # Open the MCP inspector UI

运行 Crawl 端到端测试

npm test 不会联网。npm run test:e2e 会通过真实的 MCP 客户端调用 crawl_* 工具，对接在线的 Crawl API：它会使用你提供的起始 URL 创建一个小型爬取任务（深度为 1，最多爬取 3 个 URL 和 5 个页面），等待任务完成，读取结果和其中一个页面，列出爬取任务，停止已结束的任务，并检查未找到错误。只有设置了前三个变量后才会运行：

• ZENROWS_API_KEY：具有 Crawl 访问权限的密钥。
• ZENROWS_CRAWL_API_BASE：Crawl API 的基础 URL，例如 https://api.zenrows.com/v1。如需针对本地或预发布部署进行测试，请将其指向相应部署。
• ZENROWS_E2E_CRAWL_URL：要爬取的起始 URL，即链接指向条目页面的列表页。
• ZENROWS_E2E_CRAWL_INCLUDE（可选）：包含模式；设置后，测试会检查每个结果 URL 是否都包含此模式。

export ZENROWS_API_KEY=...            # a key with Crawl access
export ZENROWS_CRAWL_API_BASE=https://api.zenrows.com/v1
export ZENROWS_E2E_CRAWL_URL=https://example.com/products/
export ZENROWS_E2E_CRAWL_INCLUDE=/product/
npm run test:e2e

爬取任务会计入密钥所属账户的用量（最多抓取 5 个页面），并占用账户的活跃任务限额（默认 3 个），该限额与 Batch 任务共享。当账户达到此限额时，测试会等待并重试，最长等待 5 分钟。

发布

合并标题遵循 Conventional Commits 规范的 PR，例如 fix(extract): ... 或 feat(crawl): ...。fix、feat 和 perf 必须带有作用域。

每次合并到 main 后，release-please 都会创建或更新 PR chore: release X.Y.Z。它会设置 package.json、 package-lock.json 和 server.json 中的版本号。请勿手动修改这些文件。

要发布，请合并该 PR。Release 工作流会运行检查、创建 标签 vX.Y.Z 和 GitHub 发布版本，并启动 Publish 工作流。该 工作流会发布到 npm 和 MCP Registry、推送 GHCR 镜像，并 部署托管服务。

要再次发布已有标签，请在 main 上手动运行 Release 工作流，并指定该标签。

如果合并发布 PR 后检查失败

发布 PR 会像其他 PR 一样运行 CI。合并后，发布 运行会再次检查代码，然后才创建标签并发布。如果该检查 失败，main 中已经有了新版本，但尚未创建标签，而 已合并的发布 PR 仍带有 autorelease: pending 标签，这会阻止 创建下一个发布 PR。恢复步骤如下：

1. 在普通 PR 中修复问题并合并。
2. 使用 .release-please-manifest.json 中的版本号，在该修复提交上 创建发布版本： gh release create vX.Y.Z --target <fix commit> --title vX.Y.Z --generate-notes --notes-start-tag <previous tag>
3. 在已合并的发布 PR 上，将标签 autorelease: pending 替换为 autorelease: tagged。
4. 在 main 上手动运行 Release 工作流，并指定标签 vX.Y.Z。

欢迎提交拉取请求和问题。

---

资源

• Zenrows MCP 完整文档
• Zenrows Fetch
• Zenrows Browser Sessions
• npm 软件包
• 获取 API 密钥

---

许可证

MIT