MrScraper MCP

用于网页抓取和 Google 搜索的 MrScraper MCP 服务

MrScraper MCP 是 MrScraper 的官方 Model Context Protocol 服务。它通过两个兼容 SDK 的工具，以及一个账户检查工具，将 AI 助手连接到网页内容和 Google 搜索。使用 scraperAPI 获取 HTML、Markdown 或截图，使用 webSearch 发现网页，并使用 status 查看套餐和令牌用量。

使用托管服务并通过 OAuth 登录，或通过 @mrscraper/mcp npm package 在本地运行开源服务。如需设置说明和客户端配置，请参阅 MrScraper MCP 文档。

该服务提供三个工具：

scraperAPI  webSearch  status

部署选项

选项	端点或命令	最适用于
托管服务	https://mcp.mrscraper.com/mcp	托管的 Streamable HTTP 连接
本地 HTTP	TRANSPORT=http npx -y @mrscraper/mcp@latest	自行管理的 HTTP 服务
本地 stdio	npx -y @mrscraper/mcp@latest	启动本地进程的 MCP 客户端

托管服务会通过 OAuth 2.1 在浏览器中为你登录，无需复制密钥。可自托管和 stdio 设置使用 MrScraper API 密钥，可在 app.mrscraper.com/api-tokens 获取；托管服务也仍接受该密钥。

连接到托管服务

将 MCP 客户端指向 https://mcp.mrscraper.com/mcp，无需凭据。服务会返回 OAuth 挑战，客户端会打开浏览器，然后你在 app.mrscraper.com 上批准连接。

claude mcp add --transport http --scope user \
  mrscraper https://mcp.mrscraper.com/mcp

对于通过文件配置的客户端，请完全省略 headers 块：

{
  "mcpServers": {
    "mrscraper": {
      "type": "http",
      "url": "https://mcp.mrscraper.com/mcp"
    }
  }
}

请使用此确切 URL，包括 /mcp 路径。它是访问令牌的颁发对象标识符；如果令牌是针对不同拼写形式的地址生成的，将会被拒绝。

批准的权限

范围	授予权限
scrape:read	webSearch
scrape:write	scraperAPI
account:read	status

未包含所需范围的工具调用会被拒绝，并返回 403 insufficient_scope；客户端会提示你授予缺少的权限。

scraperAPI 会通过 POST / 向后端提交抓取任务，这需要 scrape:write。在此范围公布之前授权的连接需要重新授权并授予该范围；仅有 scrape:read 并不能授予写入权限。

之后可在 MrScraper 账户的“已连接的应用”中断开连接。断开后，刷新令牌会立即撤销；已颁发的访问令牌会在一小时内失效。

改用 API 密钥连接

API 密钥仍可作为持有者令牌使用，可自托管部署和非 OAuth 客户端均使用此方式：

{
  "mcpServers": {
    "mrscraper": {
      "type": "http",
      "url": "https://mcp.mrscraper.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MRSCRAPER_API_KEY"
      }
    }
  }
}

请使用客户端的环境变量或机密存储功能，避免密钥出现在项目文件中。API 密钥拥有你账户的全部权限，因此不会对其强制执行范围限制。

Codex

export MRSCRAPER_API_KEY="YOUR_MRSCRAPER_API_KEY"
codex mcp add mrscraper \
  --url https://mcp.mrscraper.com/mcp \
  --bearer-token-env-var MRSCRAPER_API_KEY

请在包含 MRSCRAPER_API_KEY 的环境中启动 Codex。Codex 会在其 MCP 配置中存储环境变量名称。

Claude Code

claude mcp add \
  --transport http \
  --scope user \
  --header "Authorization: Bearer YOUR_MRSCRAPER_API_KEY" \
  mrscraper https://mcp.mrscraper.com/mcp

Claude Code 也支持项目级和本地级范围。请选择与连接可用范围相符的范围。

可直接复制的 Agent 设置提示词

Connect MrScraper MCP to this agent. Detect the current MCP client and configure a Streamable HTTP server named mrscraper at https://mcp.mrscraper.com/mcp with no credential. The server uses OAuth 2.1, so the client will open a browser to sign in. If the client cannot do OAuth, fall back to a MrScraper API key from https://app.mrscraper.com/api-tokens stored through the client's environment-variable or secret-storage mechanism and sent as Authorization: Bearer <key>. Reload the MCP client when required, then list the tools and confirm that scraperAPI, webSearch, and status are the only available tools.

选择工具

工具	适用情况
scraperAPI	你有网页 URL，需要 HTML、Markdown、截图或这些内容的组合。
webSearch	你有 Google 查询词或 Google 搜索 URL，需要搜索结果。
status	你需要查看账户方案、令牌用量或剩余令牌数。

发现工作流为 webSearch → scraperAPI。这两个网页工具都声明了 readOnlyHint: true、openWorldHint: true 和 destructiveHint: false； status 为只读且不属于开放世界。身份验证由 MCP 连接提供；没有工具需要传入 API 令牌参数。

从之前的工具集迁移

目前仅注册了 scraperAPI、webSearch 和 status。其他旧工具名称已移除。

之前的调用	替代方案
fetch	scraperAPI；使用 POST、SDK 选项，默认自动回退到浏览器。
serp	webSearch；将 query_or_url 改为 url，将 client_timeout 改为 timeout。设置 raw=false 以获取 JSON。
status	使用 status 查看账户用量；domain、from、to、action 和 api_token_name 输入项已移除。
scrape、rerun、results、result	已从此 MCP 服务中移除。

super_mode 变为 super。home_page 现在映射到 warmStart，并且接受 token_cap=0。更新后请重启服务并重新连接 MCP 客户端，以刷新 tools/list。

工具参考

scraperAPI 和 webSearch 的选项与默认值遵循 Python SDK 的 scraper_api 和 web_search 方法。MCP 工具名称使用驼峰命名法；其参数名称使用 SDK 的蛇形命名法。

scraperAPI

POST https://api.mrscraper.com/

从已知 URL 开始：

{
  "url": "https://www.scrapethissite.com/pages/simple/"
}

同时请求 HTML、Markdown 和截图：

{
  "url": "https://example.com",
  "html": true,
  "markdown": true,
  "screenshot": true,
  "super": true,
  "home_page": true,
  "geo_code": "ID",
  "timeout": 120
}

省略 browser_rendering 或将其设为 null，让服务尝试不使用浏览器， 并在必要时回退到浏览器加载。true 会强制使用浏览器加载，false 则会禁用浏览器加载。即使 browser_rendering=false，截图也始终会强制使用浏览器加载。super 独立选择真实设备路由。

JSON 请求体包含 url、maxRetries 和可选的 tokenCap。页面选项为查询参数。对于 API 密钥，请求还会包含与 SDK 兼容的 token 查询参数以及 Authorization/x-api-token 请求头。OAuth JWT 仅通过 Authorization 发送。

输入	默认值	API 映射 / 用途
url	必填	请求体中的 url；绝对 HTTP(S) 页面 URL。
html	true	查询参数 html；请求 HTML。
markdown	false	查询参数 markdown；请求 Markdown。
timeout	120	查询参数 timeout；1 到 300 秒的整数。传输允许额外 30 秒。
geo_code	"US"	查询参数 geoCode；代理国家/地区代码。
proxy_country	省略	查询参数 proxyCountry；兼容用的国家/地区字段。
browser_rendering	省略	查询参数 browserRendering；true/false，或省略/设为 null 以自动回退。
super	false	启用时设置查询参数 super=true。
use_proxy	true	禁用时设置查询参数 useProxy=false。
proxy	省略	查询参数 proxy；自定义 username:password@host:port 代理。
wait_for_selector	省略	查询参数 waitForSelector；要等待的 CSS 选择器。
home_page	false	启用时设置查询参数 warmStart=true。
screenshot	false	查询参数 screenshot=true；同时设置 browserRendering=true。
block_resources	false	查询参数 blockResources=true；屏蔽图片、CSS 和字体。
bypass_proxy	false	查询参数 bypassProxy=true；绕过代理/屏蔽资源选项。
cookie_jar	省略	查询参数 cookieJar；Cookie 配置字符串。
headers	省略	查询参数 headers；目标请求头，可以是对象或 JSON 字符串。
max_retries	3	请求体中的 maxRetries；非负整数，0 表示禁用重试。
token_cap	省略	请求体中的 tokenCap；非负整数重试令牌预算。
stream	省略	查询参数 stream；响应会缓冲到常规 MCP 封装中。
discard_token_secret	""	可选的 x-discard-token-secret 请求头。

webSearch

POST https://sync.scraper.mrscraper.com/api/google/serp/v2/sync

解析后的 Google 结果请求：

{
  "url": "MrScraper web scraping",
  "raw": false,
  "region": "id",
  "language": "id",
  "page": 1,
  "format": "json"
}

raw=true 是与 Python SDK 兼容的默认值，无论 format 为何，都会请求 HTML。 设置 raw=false 和 format="json" 可获取解析后的结果。

Google 搜索 URL 可提供查询词、地区和页码：

{
  "url": "https://www.google.com/search?q=web+scraping&gl=us&hl=en&start=20",
  "raw": false
}

这会得出 query="web scraping"、region="us"、language="en" 和 page=3。显式选项会覆盖从 URL 中得出的值。

输入	默认值	请求映射 / 用途
url	必填	搜索文本或 Google URL；规范化为请求体中的 query。
raw	true	强制请求体中的 format="html"；设为 false 时允许使用 format。
format	"json"	raw 为 false 时，请求体中的 format，可为 json 或 html。
region	URL 值或省略	请求体中的 region；覆盖 gl。
language	URL 值或省略	请求体中的 language；覆盖 hl。
page	URL 值或省略	请求体中的 page；从 1 开始的正整数，覆盖 start。
render_js	false	请求体中的 renderJs；渲染动态搜索功能。
timeout	600	本地 HTTP 截止时间，单位为秒；不会包含在请求体中。

status

GET https://api.app.mrscraper.com/api/v1/subscription-accounts

status 不接受任何输入。它会返回已连接账户的身份信息（名称、电子邮件和验证状态）、订阅状态、令牌上限、令牌用量、剩余令牌数、用量百分比、速率限制、自动续订状态和续订日期。 它只复制这些字段，因此原始账户记录中的 API 密钥和 Stripe 标识符不会传递给客户端。

{
  "kind": "mrscraper-cli-status-summary",
  "source_endpoints": ["/subscription-accounts"],
  "status_code": 200,
  "data": {
    "account": {
      "subscription_status": "active",
      "enterprise": false,
      "token_usage": 61240,
      "token_limit": 100000,
      "token_remaining": 38760,
      "usage_percent": 61.24,
      "rate_limit": 0,
      "rate_ttl": 0,
      "auto_renew": true,
      "ends_at": "2026-12-01T00:00:00.000Z",
      "user": {
        "name": "Ada",
        "email": "[email protected]",
        "verified": true
      }
    }
  }
}

OAuth 连接需要 account:read 权限范围才能使用 status。

响应封装

scraperAPI 和 webSearch 会在 structuredContent 和 JSON 文本中返回 status_code、data 和 headers。JSON 响应体会被解析；其他响应体则保留为文本。 status 会返回上文所示的摘要。

scraperAPI 响应会在 data 中包含请求的表示形式； screenshot 是经过 base64 编码的 JPEG，x-status-code 是目标页面的 状态：

{
  "status_code": 200,
  "data": {
    "html": "<!DOCTYPE html>...",
    "markdown": null,
    "screenshot": null,
    "token_usage": 3,
    "runtime": 18.02,
    "retry_count": 0,
    "error": null
  },
  "headers": {
    "content-type": "application/json",
    "x-status-code": "200",
    "token_usage": "3"
  }
}

解析后的 webSearch 响应（raw=false）会在 data.data.organic 中包含自然搜索结果。

失败时会包含 error，并将 MCP isError 设为 true。网络故障的 status_code 为 null。包含凭证的响应头和 JSON 元数据会被过滤；网络错误中的签名查询凭证会被脱敏。

手动测试：每次测试一个工具

scripts/test-tools.ts 会通过 stdio 启动已编译的本地 MCP 服务，验证恰好暴露了三个工具，调用一个工具，打印其响应，然后退出。无需单独打开服务终端。 运行程序会加载 .env，或从你的 shell 中读取 MRSCRAPER_API_KEY / MRSCRAPER_API_TOKEN。每次工具调用都会使用实时的 MrScraper 服务。

请在仓库目录中分别运行以下命令：

1. 安装依赖：

   npm ci
   

2. 构建当前服务：

   npm run build
   

3. 设置 API 密钥：

   export MRSCRAPER_API_KEY="YOUR_MRSCRAPER_API_KEY"
   

4. 测试 scraperAPI：

   npm run test:manual -- scraperAPI --url "https://www.scrapethissite.com/pages/simple/"
   

5. 测试 webSearch：

   npm run test:manual -- webSearch --query "MrScraper web scraping"
   

6. 测试 status：

   npm run test:manual -- status
   

webSearch 示例明确请求 raw=false、format="json"、美国结果和英文。 每条命令成功时都会打印 Tools: scraperAPI, webSearch, status 和 PASS <tool>。成功时退出代码为 0，工具或连接失败时为 1，命令参数无效时为 2。

传入完整的 JSON 对象即可测试任何受支持的选项：

npm run test:manual -- scraperAPI --args '{"url":"https://example.com","markdown":true,"screenshot":true,"super":true}'

npm run test:manual -- webSearch --args '{"url":"web scraping","raw":false,"region":"id","language":"id","page":1,"render_js":true}'

若要测试已运行的 HTTP MCP 服务，请追加 --target http://127.0.0.1:8000/mcp。测试本地 stdio 时，源代码更改后需重新构建。 npm run test:manual -- --help 会列出运行程序选项。

在本地运行服务

需要 Node.js 20 或更高版本。

git clone https://github.com/mrscraper-com/mrscraper-mcp.git
cd mrscraper-mcp
npm ci
npm run build

Streamable HTTP

TRANSPORT=http npm start

默认端点为 http://127.0.0.1:8000/mcp。

{
  "mcpServers": {
    "mrscraper": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MRSCRAPER_API_KEY"
      }
    }
  }
}

stdio

{
  "mcpServers": {
    "mrscraper": {
      "command": "npx",
      "args": ["-y", "@mrscraper/mcp@latest"],
      "env": {
        "MRSCRAPER_API_KEY": "YOUR_MRSCRAPER_API_KEY"
      }
    }
  }
}

Stdio 凭据优先级为 MRSCRAPER_API_KEY，然后是 MRSCRAPER_API_TOKEN。

身份验证与安全

传输方式	凭据
托管或本地 HTTP	OAuth 2.1 访问令牌，或 MrScraper API 密钥，格式为 Authorization: Bearer
本地 stdio	MRSCRAPER_API_KEY，然后是 MRSCRAPER_API_TOKEN

HTTP 传输采用 OAuth 2.1 资源服务器。它在 /.well-known/oauth-protected-resource（以及带有 /mcp 路径后缀的变体）发布 RFC 9728 受保护资源元数据。对于未经身份验证的请求，服务器会返回 401 和一个 WWW-Authenticate 标头，其中注明该文档的位置；客户端据此发现应将你重定向到何处进行登录。

访问令牌会根据授权服务器发布的 JWKS 在本地进行验证。令牌的 aud 声明必须指向此服务器，因此，为其他 MrScraper 服务签发的令牌无法在此处重放。

API 密钥会在执行工具前通过 MrScraper 账户端点进行验证。无论使用哪种凭据，每个 HTTP 请求都会使用其调用方自己的凭据；HTTP 传输绝不会使用服务器环境中的凭据。

服务器会过滤包含凭据的响应标头。已解析的 JSON 凭据元数据以及生成的 curl 命令中嵌入的凭据都会被脱敏。页面内容仍可通过 data 获取。

接受来自受信任本地源、claude.ai 和 chatgpt.com 的浏览器源请求，也接受通过 MRSCRAPER_ALLOWED_ORIGINS 配置的精确源。服务间 MCP 客户端通常不带 Origin 标头进行连接。发现文档会在源检查前提供服务，因为任何客户端都必须先能够读取这些文档，才能获得凭据。

交互式小组件

webSearch 会为已解析的 JSON 结果提供一个自包含的 Google 结果小组件。HTML 响应会显示提示，要求获取已解析的结果。status 会提供账户小组件，显示套餐、令牌用量和用量表盘。不支持 MCP Apps 的宿主会显示常规 JSON 工具响应。

每个小组件都是自包含文档，其脚本和样式均内联，因为严格的宿主 CSP 会阻止任何外部内容。每个小组件都声明了空的网络允许列表，因为它们只渲染工具已返回的数据。源文件位于 ui/；npm run build:widgets 会将它们打包到 src/widgets/bundles.generated.ts 中，npm run build 会自动执行此操作。

Docker

docker build -f docker/Dockerfile -t mrscraper-mcp .
docker run --rm -p 8000:8000 mrscraper-mcp

镜像会绑定到 0.0.0.0。请应用适用于部署环境的网络控制，并保持启用 Bearer 身份验证。

环境变量

变量	默认值	用途
TRANSPORT	stdio	选择 stdio 或 http。
HOST	127.0.0.1	HTTP 绑定地址；Docker 镜像使用 0.0.0.0。
PORT	8000	HTTP 监听端口。
MRSCRAPER_API_KEY	-	主要的 stdio 凭据。
MRSCRAPER_API_TOKEN	-	备用的 stdio 凭据（Python SDK 也会使用）。
MRSCRAPER_HTTP_AUTH	1	启用 HTTP bearer 验证。
MRSCRAPER_OAUTH	1	除 API 密钥外，也接受 OAuth 2.1 访问令牌。
MRSCRAPER_MCP_PUBLIC_URL	https://mcp.mrscraper.com	公共源站；<origin>/mcp 是必需的令牌受众。
MRSCRAPER_OAUTH_ISSUER	https://api.app.mrscraper.com	授权服务器签发者。
MRSCRAPER_OAUTH_JWKS_URL	<issuer>/.well-known/jwks.json	用于验证访问令牌的密钥集。
MRSCRAPER_ALLOWED_ORIGINS	-	允许调用 HTTP 服务的浏览器源站列表，以逗号分隔。
MRSCRAPER_API_BASE_URL	MrScraper platform API	用于开发和测试的平台端点覆盖值。
MRSCRAPER_FETCH_BASE_URL	MrScraper Web Unblocker	爬取 API 端点覆盖值。
MRSCRAPER_SYNC_BASE_URL	MrScraper synchronous scraper API	网络搜索端点覆盖值。
MRSCRAPER_LOG_HTTP_PAYLOAD	off	启用可信环境中的请求正文诊断。
MRSCRAPER_LOG_HTTP_PAYLOAD_MAX	8192	诊断负载的最大长度。

故障排除

• 连接错误： 确认服务 URL 以 /mcp 结尾，并在配置更改后重新加载 MCP 客户端。
• 401 Unauthorized： 对于 OAuth，请重新连接服务，以便客户端再次运行登录流程。对于 API 密钥，请确认 HTTP 使用的 bearer 密钥或 stdio 使用的环境密钥。
• 403 insufficient_scope： 令牌缺少工具所需的作用域。请重新连接并批准额外权限。对于 scraperAPI，令牌必须包含 scrape:write；对于 webSearch，必须包含 scrape:read。
• 登录成功但工具无法使用： 确认服务 URL 完全是 https://mcp.mrscraper.com/mcp；令牌受众与该 URL 绑定。
• 403 Forbidden Origin： 将准确的浏览器源站添加到 MRSCRAPER_ALLOWED_ORIGINS。
• 工具输入错误： 对照工具参数表和文档中与 SDK 兼容的默认值，检查调用内容。
• 上游超时： 将 scraperAPI.timeout（最高 300 秒）或 webSearch.timeout 调大，以适应目标所需的更长请求时限。
• 缺少新工具： 启动新的客户端会话，并检查 tools/list 中是否恰好包含 scraperAPI 和 webSearch。

开发

npm ci
npm run format:check
npm run lint
npm test
npm run build
npm pack --dry-run

对正在运行的 HTTP 服务进行冒烟测试：

npm run test:mcp -- \
  --target http://127.0.0.1:8000/mcp \
  --token "$MRSCRAPER_API_KEY"

npm run test:e2e 使用手动运行器，依次针对运行中的 MrScraper 服务测试这两个新工具。使用 -- --url URL --query QUERY 自定义目标，或使用 -- --target http://127.0.0.1:8000/mcp 通过 HTTP 进行测试。

MCP Registry

托管服务的 MCP Registry 清单定义在 server.json 中。它描述了 Streamable HTTP 端点，并链接到此代码库和设置文档。

.github/workflows/publish-mcp-registry.yml 会将 server.json 发布为 io.github.mrscraper-com/mrscraper-mcp。可在 Actions 选项卡中运行此工作流（Publish to MCP Registry → Run workflow），也可以推送与 server.json 中版本匹配的 v* 标签。该工作流使用 GitHub OIDC 进行身份验证，此机制授予此代码库 io.github.mrscraper-com/* 命名空间；交互式 mcp-publisher login github 仅适用于组织所有者。如果 server.json 和 package.json 的版本不同，工作流将失败。

详情请参阅官方 Registry 发布指南。Registry 版本不可变，因此发布更改后的元数据时，请在 server.json 中使用新版本。发布此清单会注册托管服务；它不会发布新的 npm 包。

许可证

MIT。请参阅 LICENSE。