Spicrawl

Spicrawl MCP 服务：为 Claude、Cursor 和 AI Agent 提供网页抓取

若要让 Claude、Cursor 或其他 AI Agent 抓取网站，请连接 Spicrawl MCP 服务。添加托管端点 https://mcp.spicrawl.com/mcp（或在本地运行 npx -y @spicrawl/mcp），并提供 Spicrawl API 密钥，Agent 就可以调用 spicrawl_scrape，以 Markdown、文本、HTML 或 JSON 格式读取任意 URL。它可以渲染 JavaScript 页面、提取结构化数据、在单个批量任务中抓取最多 10,000 个 URL、截图并保留已登录的浏览器会话；所有功能都以原生 spicrawl_* 工具的形式提供，可在 Claude Code、Claude Desktop、Cursor、VS Code、Windsurf、Gemini CLI 和 Codex 中使用。免费套餐每月包含 1,000 个积分。

文档 · 获取 API 密钥 · TypeScript SDK · 命令行工具 · Agent 插件 · 更新日志

安装来源： npm · Smithery · Glama · MCP Registry · Dify 插件 · Cursor Directory

1. 在 app.spicrawl.com 创建 API 密钥。密钥以 spicrawl_live_ 或 spicrawl_test_ 开头。

2. 连接托管端点 https://mcp.spicrawl.com/mcp（MCP Streamable HTTP，无需安装）：

   export SPICRAWL_API_KEY=spicrawl_live_...
   claude mcp add --transport http spicrawl https://mcp.spicrawl.com/mcp \
     --header "Authorization: Bearer $SPICRAWL_API_KEY"
   

   Codex：codex mcp add spicrawl --url https://mcp.spicrawl.com/mcp --bearer-token-env-var SPICRAWL_API_KEY

3. 或者通过 stdio 在本地运行（Node.js 20+），适用于只能启动本地服务的客户端：

   claude mcp add spicrawl --env SPICRAWL_API_KEY=$SPICRAWL_API_KEY -- npx -y @spicrawl/mcp
   

4. 向你的 Agent 提问：“使用 Spicrawl 将 https://example.com/pricing 读取为 Markdown，并列出每个套餐及其价格。” 它会调用 spicrawl_scrape，并以 Markdown 格式返回页面。

两种传输方式都提供相同的 spicrawl_* 工具（共定义了 25 个；在远程浏览器上线之前，托管端点会列出 24 个，见工具），并且每次调用都使用你的密钥，具有与直接 API 调用相同的权限范围、限制和额度。

功能介绍

• 将任意 URL 抓取为 Markdown、文本、HTML、JSON 信封或打印版 PDF，只需使用一个工具 spicrawl_scrape。默认格式为 Markdown，并会将页面精简为主要内容。
• 使用 render: true 渲染 JavaScript（3 个额度）。普通抓取需 1 个额度；截图、PDF 和 actions 使用完整浏览器（8 个额度）；mode: "auto" 则会在普通抓取无效时升级到浏览器，并且只按成功的级别计费（价格表）。你无需自行选择渲染方式；Spicrawl 会选择能够满足请求的最低成本方案。
• 使用 CSS/XPath 选择器映射（extract）提取结构化数据，或提取页面公开的 JSON-LD、OpenGraph、Twitter Card 和微数据（autoparse）。
• 在采集前通过 8 种类型化浏览器操作控制页面：click、fill、wait_for、wait_for_navigation、scroll（包括无限滚动）、select、evaluate 和 screenshot。
• 返回模型可查看的截图和 PDF：截图以 MCP 图像块形式返回（每张最大 5 MB 的 base64），打印页面则以 application/pdf 资源块形式返回（最大 10 MB）。
• 批量抓取数千个 URL，作为一个异步任务，每次调用最多可处理 10,000 项。提供 9 个工具，用于提交任务、轮询、分页获取结果、重试、取消任务，以及保持任务开放以便发现更多 URL 后追加。
• 使用持久会话保持浏览器登录状态：Cookie、存储数据和固定的渲染级别会在多次抓取间复用。
• 使用用量和请求日志工具回答“这花了多少钱？”，并可在 Agent 内部阅读 Spicrawl 文档。

使用场景

• 将文档抓取到 RAG 知识库。 使用 spicrawl_scrape 将文档页面读取为简洁的 Markdown（Markdown 默认启用 main_content_only），或者通过一个 spicrawl_batch_submit 任务一次性排队处理最多 10,000 个 URL。Spicrawl 返回 Markdown；分块和嵌入由你负责。参见知识库指南。
• 监控价格。 使用 extract 选择器映射或 autoparse 获取产品标题、价格和库存情况，并设置 cache: false 以获取最新信息。普通抓取需 1 个额度，渲染抓取需 3 个额度。按你自己的计划运行。参见价格监控。
• 提取招聘信息。 从招聘网站收集职位信息，包括无限滚动页面（使用 render: true 和 scroll 操作），并将其提取为结构化字段。参见招聘信息。
• 读取 JavaScript 密集型页面。 当普通抓取返回空壳页面时，调用 spicrawl_scrape 并设置 render: true（3 个额度），让页面先完成构建。

抓取前，请检查各网站的服务条款和 robots.txt。

使用哪个工具

• 如果现在需要某个页面的内容或数据，请使用 spicrawl_scrape。
• 如果页面为空白，或是没有 JavaScript 的骨架页面，请再次调用 spicrawl_scrape，并设置 render: true。
• 如果你了解页面结构，请使用带 CSS 选择器的 extract；如果不了解，请尝试 autoparse。
• 如果 URL 超过约 20 个，请使用 spicrawl_batch_submit，然后调用 spicrawl_batch_status 和 spicrawl_batch_results。
• 如果你在处理过程中发现 URL，请使用 open: true 提交，并通过 spicrawl_batch_add_items 追加，最后调用 spicrawl_batch_close。
• 如果必须先登录，请使用 spicrawl_session_create，并将其 id 作为 session_id 传给 spicrawl_scrape。
• 如果调用失败且你需要了解原因，请使用请求 ID 调用 spicrawl_request_get，或使用 only_errors 调用 spicrawl_requests_list。
• 如果你不确定某个参数或错误代码，请先使用 spicrawl_docs_search，不要猜测。

工具

共有 25 个工具，按任务分组。托管端点会列出 24 个工具，直到远程浏览器启动：无密钥的 tools/list 和服务卡片不会列出 spicrawl_browser_connect_url（即将推出），而使用你的密钥打开的会话和 stdio 包（npx -y @spicrawl/mcp）会列出全部 25 个工具。工具会拒绝未知参数，因此字段拼写错误时会报错并指出字段名称，而不是悄然忽略。每个工具都设有 title，并明确标注 readOnlyHint、destructiveHint 和 openWorldHint，让客户端知道哪些调用需要确认：spicrawl_scrape 不是只读工具（其 method 和 actions 可以提交表单），而 spicrawl_batch_cancel、spicrawl_session_release 和 spicrawl_session_delete 具有破坏性。每个工具还声明了 outputSchema，并会在原有文本之外返回与之匹配的 structuredContent，因此客户端可以读取字段（credits、status、next_cursor 等），而无需解析文本。架构会列出 Agent 可以依赖的内容，同时保持开放：API 日后新增的字段会原样传递，状态和层级则是普通字符串。返回文档或 JSON 数组的工具（spicrawl_docs_read、spicrawl_batch_task_content）会将其置于 structuredContent 下的 content 中。完整参数参考：docs.spicrawl.com/agents/mcp。

将网站抓取为 Markdown

批量抓取多个 URL

浏览器会话

用量和请求历史

文档

即将推出

spicrawl_browser_connect_url 将生成一次性 CDP WebSocket URL，以便通过任意 CDP 客户端驱动由 Spicrawl 托管的浏览器；目前尚不支持远程浏览器。这是第 25 个工具，也是托管的无密钥工具列表和服务卡片中唯一未列出的工具（其中有 24 个工具）。这些模式还预先接受 ai_extract、stealth、extract_preset、premium_proxy、proxy_country 和 sticky_key，但这些功能尚未发布。Agent 暂时不要发送这些参数。若只想列出目前可用的工具，请设置 SPICRAWL_MCP_HIDE_UNAVAILABLE=1（参见环境变量）。

示例提示词

• “将 https://example.com/pricing 抓取为 Markdown，并总结各个套餐。”
• “从此 URL 获取产品名称、价格和库存状态。”（使用 spicrawl_scrape 的 extract 或 autoparse）
• “在 cookie 横幅消失后，对 https://example.com 进行整页截图。”（使用 render、actions、screenshot_fullpage）
• “抓取这 500 个 URL，并提供每个页面的标题。”（使用 spicrawl_batch_submit，然后使用 spicrawl_batch_results）
• “为什么我上一次抓取失败了？”（先使用 spicrawl_requests_list 并设置 only_errors，然后使用 spicrawl_request_get）
• “我这个月用了多少额度？”（使用 spicrawl_usage_summary）

配置 MCP 客户端

将密钥放入 SPICRAWL_API_KEY，并在客户端支持的配置中引用它，这样密钥就不会写入已提交的文件。

claude mcp add --transport http spicrawl https://mcp.spicrawl.com/mcp \
  --header "Authorization: Bearer $SPICRAWL_API_KEY"

{
  "mcpServers": {
    "spicrawl": {
      "type": "http",
      "url": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer ${SPICRAWL_API_KEY}" }
    }
  }
}

claude plugin marketplace add OfficialSpicrawl/agent-plugins
claude plugin install spicrawl@spicrawl-plugins

{
  "mcpServers": {
    "spicrawl": {
      "command": "npx",
      "args": ["-y", "@spicrawl/mcp"],
      "env": { "SPICRAWL_API_KEY": "spicrawl_live_..." }
    }
  }
}

{
  "mcpServers": {
    "spicrawl": {
      "url": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SPICRAWL_API_KEY}" }
    }
  }
}

{
  "inputs": [
    { "type": "promptString", "id": "spicrawl-api-key", "description": "Spicrawl API key", "password": true }
  ],
  "servers": {
    "spicrawl": {
      "type": "http",
      "url": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer ${input:spicrawl-api-key}" }
    }
  }
}

devin mcp add spicrawl https://mcp.spicrawl.com/mcp -H "Authorization: Bearer $SPICRAWL_API_KEY"

{
  "mcpServers": {
    "spicrawl": {
      "serverUrl": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SPICRAWL_API_KEY}" }
    }
  }
}

export SPICRAWL_MCP_BEARER="$SPICRAWL_API_KEY"

{
  "mcpServers": {
    "spicrawl": {
      "httpUrl": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer $SPICRAWL_MCP_BEARER" }
    }
  }
}

codex mcp add spicrawl --url https://mcp.spicrawl.com/mcp --bearer-token-env-var SPICRAWL_API_KEY

[mcp_servers.spicrawl]
url = "https://mcp.spicrawl.com/mcp"
bearer_token_env_var = "SPICRAWL_API_KEY"

[mcp_servers.spicrawl]
command = "npx"
args = ["-y", "@spicrawl/mcp"]
env = { SPICRAWL_API_KEY = "spicrawl_live_..." }

如果未设置任何文档变量，指向可自托管 API 的服务会从该 API 自身读取文档，路径为 <SPICRAWL_PUBLIC_BASE_URL or SPICRAWL_BASE_URL>/docs。

通过 HTTP 自托管 MCP 服务

托管端点运行的是此软件包的 Streamable HTTP 服务。要运行自己的服务：

SPICRAWL_MCP_ADDR=127.0.0.1:8090 \
SPICRAWL_BASE_URL=https://api.spicrawl.com \
npx -y @spicrawl/mcp --http

• 在 HTTP 模式下，SPICRAWL_BASE_URL 默认为 http://127.0.0.1:8080（同一主机上的 Spicrawl API），而不是公共 API。将其设置为 https://api.spicrawl.com，即可连接公共 API。
• MCP 服务在 POST/GET/DELETE /mcp 上；存活检查位于 GET /healthz（无需身份验证）。
• GET /.well-known/mcp/server-card.json（无需身份验证，Cache-Control: public, max-age=3600）是面向无法在没有密钥的情况下扫描 /mcp 的 Smithery 等目录的静态服务卡片，其中包含 serverInfo、传输方式、Bearer 身份验证和工具列表。工具列表读取自与 tools/list 相同的定义，就像启用了 SPICRAWL_MCP_HIDE_UNAVAILABLE 一样：共 24 个工具，不包括 spicrawl_browser_connect_url。使用密钥打开的会话也会列出该工具，除非设置了此变量。
• 未提供任何密钥时，/mcp 仅响应发现请求：initialize、ping、initialized 通知和 tools/list（与服务卡片相同的 24 个工具列表；不会签发 Mcp-Session-Id，也不会向上游发送任何内容）。任何其他请求，包括 tools/call，都会返回 401；发送格式错误的密钥或指定会话的请求也会返回 401。不带会话的 GET 会返回 405。
• 每位调用方都使用自己的密钥，以 Authorization: Bearer spicrawl_live_... 的形式发送；如果网关无法发送 Bearer 前缀，则可使用原始 Authorization: spicrawl_live_...、x-api-key 或 api-key 标头（参见上文“Smithery 和其他网关”；切勿使用查询参数）。会话打开前会先向 API 验证密钥（API 拒绝时返回 401，无法连接 API 时返回带有 Retry-After 的 503），并且会话会固定使用打开它的密钥。
• 服务使用纯 HTTP。通过网络发送密钥前，请将其置于 TLS 后面。

ChatGPT 端点（OAuth）

同一进程可为 ChatGPT 应用提供另一个受限的 MCP 端点。除非启用了 SPICRAWL_CHATGPT_ENABLED，否则该端点处于关闭状态；无论如何，/mcp 都不会改变。

身份验证仅接受 OAuth 访问令牌（spicrawl_oat_…）：

• 没有令牌：返回 401，并附带 WWW-Authenticate: Bearer resource_metadata="https://mcp.spicrawl.com/.well-known/oauth-protected-resource/chatgpt/mcp", scope="scrape batch"。
• 无效、未激活、已过期或受众错误的令牌，或 API 密钥（spicrawl_live_…/spicrawl_test_…；此处绝不接受）：返回相同的 401，并附带 error="invalid_token", error_description="…"。
• 令牌的作用域未涵盖的工具调用：返回 403，并附带 error="insufficient_scope"。spicrawl_scrape 需要 scrape，批处理工具需要 batch，文档工具只需要有效令牌。
• 授权服务器无法访问或拒绝此服务的密钥：返回带有 Retry-After 的 503。 每个令牌都会通过 POST <issuer>/api/oauth/introspect 检查（Authorization: Bearer <SPICRAWL_OAUTH_INTROSPECT_SECRET>，表单正文为 token=…）。只有 active: true 且 aud 与资源相同的令牌才会被接受。肯定结果会按令牌的 SHA-256 值缓存，最长 30 秒，且绝不会超过其 exp。工具会使用内省结果返回的 api_key 调用上游；该密钥和令牌都不会被记录。如果 API 在调用过程中拒绝该密钥，工具会返回错误，其 _meta["mcp/www_authenticate"] 中包含新的 invalid_token 挑战，并将该令牌从缓存中移除。

该端点列出六个工具，每个工具都明确设置了 readOnlyHint/destructiveHint/openWorldHint，并带有标题和 securitySchemes: [{type: "oauth2", scopes: [...]}]（也包含在 _meta.securitySchemes 中）：

此处的 spicrawl_scrape 为只读工具，与 /mcp 上的不同：该端点只发送 GET 请求，不包含 method、正文、标头或 actions。spicrawl_batch_submit 不是只读工具，因为它会创建任务。

如果结果页面列出的成功项目没有内容（这会发生在任务仍在完成过程中），spicrawl_batch_results 会通过 GET /v1/batch/{id}/tasks/{seq}/content 补全内容。每页最多获取 25 个项目和 2 MiB。暂时无法读取的项目会返回 unavailable，超过大小上限的项目会返回 omitted。

所有其他参数都会被拒绝，而非丢弃。结果会保留内容、网站状态和已扣除的积分；请求 ID、时间戳、引擎和代理详情、存储引用及项目 ID 均不会返回。

全局安装后（npm install -g @spicrawl/mcp），命令为 spicrawl-mcp（别名为 spicrawl-mcp-server），支持 --http、--version 和 --help。

常见问题

哪个 MCP 服务可以抓取 JavaScript 网站？

Spicrawl MCP 服务可以。调用 spicrawl_scrape 并设置 render: true（3 个积分），页面就会在浏览器中加载、运行脚本，并以处理完成的 Markdown、文本、HTML 或 JSON 格式返回。对于较晚出现的内容，可添加包含 CSS 选择器的 wait_for；也可以设置 mode: "auto"，先尝试普通抓取，仅在需要时升级到更强的渲染方式。Spicrawl 会为每个请求选择渲染方式，并按实际提供服务的等级计费（fetch、js 或 browser，在 JSON 结果中以 engine 报告）；没有可用于选择渲染方式的参数。

如何让 Claude 访问 Web？

使用 API 密钥将 Spicrawl MCP 服务连接到 Claude。在 Claude Code 中：

claude mcp add --transport http spicrawl https://mcp.spicrawl.com/mcp \
  --header "Authorization: Bearer $SPICRAWL_API_KEY"

之后，Claude 就可以通过调用 spicrawl_scrape 读取你提供的任意 URL。Spicrawl 按 URL 读取网页，并非搜索引擎。如需了解 Claude Desktop 的安装方法，请参阅下方的安装解答。

有免费套餐吗？

有。测试期间，每个组织都使用同一套餐，每月有 1,000 个积分。普通抓取消耗 1 个积分，JavaScript 渲染消耗 3 个积分，全浏览器渲染（截图、PDF、actions）消耗 8 个积分。请求失败不扣积分，缓存命中按存储该缓存时的抓取价格计费。当月积分用完后，调用会失败并返回 ERR::LIMIT::QUOTA_EXCEEDED，直到积分重置。请参阅积分。

它能处理受机器人防护的页面吗？

只能使用你自己的代理。将代理传入 proxy（一个 http:// URL；住宅代理效果最佳）。当网站返回 Cloudflare 托管质询时，Spicrawl 会检测到该情况，将请求切换到使用同一代理出口的完整浏览器渲染，并返回真实页面，费用为 8 个额度点。如果每一步都受到质询，你会收到 ERR::UPSTREAM::CHALLENGE，且不扣费。成功的可能性较高，但不保证成功；Spicrawl 不会解决 CAPTCHA。使用默认共享池时，受到质询的页面会返回该错误。请参阅抓取 Cloudflare 保护的页面。

如何在 Cursor 或 Claude Desktop 中安装？

**Cursor：**点击上方的 Add to Cursor，或将以下内容添加到 .cursor/mcp.json，并在设置好 SPICRAWL_API_KEY 的情况下启动 Cursor：

{
  "mcpServers": {
    "spicrawl": {
      "url": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SPICRAWL_API_KEY}" }
    }
  }
}

Claude Desktop 只启动本地（stdio）服务，因此请运行该软件包。将以下内容添加到 claude_desktop_config.json 并重启应用：

{
  "mcpServers": {
    "spicrawl": {
      "command": "npx",
      "args": ["-y", "@spicrawl/mcp"],
      "env": { "SPICRAWL_API_KEY": "spicrawl_live_..." }
    }
  }
}

请在 app.spicrawl.com 获取密钥。Claude Code、VS Code、Windsurf、Gemini CLI 和 Codex 的设置步骤见设置 MCP 客户端。

它能抓取整个网站吗？

目前没有单独的抓取工具。使用 links: true 抓取页面以获取其链接，然后将这些链接传入一个已打开的批处理任务（open: true 和 spicrawl_batch_add_items）。

其他问题

有托管的 Spicrawl MCP 服务吗？

有：https://mcp.spicrawl.com/mcp，采用 MCP Streamable HTTP，通过 Authorization: Bearer <API key> 进行身份验证，因此无需安装任何内容。

它支持 OAuth 吗？

/mcp 不支持：它只接受 Spicrawl API 密钥，因此对于在收到 401 时尝试使用 OAuth 的客户端，请关闭该端点的 OAuth。单独的 ChatGPT 端点 /chatgpt/mcp 仅接受 OAuth 访问令牌，且仅在运营方启用时可用。

我应该使用 MCP 服务、SDK 还是 CLI？

当 AI Agent 需要将 Spicrawl 作为工具调用时，请使用 MCP 服务。在你自己的 TypeScript 或 JavaScript 代码中使用 @spicrawl/sdk，在终端或 Shell 脚本中使用 @spicrawl/cli，其他语言则使用 REST API。

故障排除

不带密钥运行 curl -i https://mcp.spicrawl.com/mcp 会收到 401：这说明该端点可访问。

相关软件包

• @spicrawl/sdk：Spicrawl API 的官方 TypeScript SDK。
• @spicrawl/cli：Spicrawl 命令行界面。
• OfficialSpicrawl/agent-plugins：打包了此服务和 Spicrawl 技能的插件，适用于 Claude Code、Codex、Cursor、Gemini CLI 等。

链接

• 文档：docs.spicrawl.com/agents/mcp
• 面向大模型的文档：docs.spicrawl.com/llms.txt
• 控制面板和 API 密钥：app.spicrawl.com
• 问题：github.com/OfficialSpicrawl/mcp/issues
• 安全：SECURITY.md。切勿提交 API 密钥；如果密钥泄露，请在 app.spicrawl.com 撤销。

发布到 MCP Registry

server.json 列出了 npm/stdio 软件包和托管的 Streamable HTTP 端点，二者均位于 io.github.OfficialSpicrawl/mcp 下。安装服务的用户 需要提供 API 密钥；清单中不应包含密钥。

现有的 release 工作流会在 npm 任务成功后，将内容发布到 MCP Registry；触发条件是推送到 main 或在 main 上手动运行。Registry 身份验证使用 GitHub OIDC（id-token: write），因此无需新增密钥、设备登录或 DNS 记录。npm 发布仍使用现有的 NPM_TOKEN 密钥。

要发布版本，请运行 npm version --no-git-tag-version X.Y.Z，更新变更日志， 并将更改提交到 main。npm 版本钩子会同步 server.json 中的两个版本。 如果手动编辑 package.json，请运行 npm run registry:sync。 CI 使用 Ajv 根据官方 $schema 检查清单，并在 npm 发布前拒绝名称 或版本不一致的情况。要在本地运行此检查：

npm ci
npm run registry:validate
# Offline: pass a downloaded copy of the exact server.json $schema URL.
npm run registry:validate -- /path/to/server.schema.json

Registry 任务会在发布前检查已发布的 npm 软件包是否具有匹配的 mcpName。 如果 Registry 中已存在该版本，则会跳过；查询失败则会停止 任务。要重试 Registry 发布失败，或列出当前已发布的 npm 版本，请在 main 上再次运行 release 工作流。要更改现有条目的元数据，请使用新版本。发布器二进制文件已固定版本，且其下载文件会使用发布校验和进行检查；升级 CLI 时，请更新 release.yml 中的版本。

请在 https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.OfficialSpicrawl/mcp 验证发布结果。 必须先将工作流合并到 OfficialSpicrawl/mcp，OIDC 才能发布该命名空间。Fork 的拉取请求会进行验证和测试，但绝不会运行 Registry 任务。

官方参考资料：发布快速入门、 GitHub Actions 和远程服务。

许可证

Apache-2.0