mrscraper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MrScraper CLI

Use this skill for setup, authentication, command selection, shared output handling, account status, and troubleshooting. Load the focused skills for page retrieval and Google search.

The CLI has three data commands:

Command	Purpose
`mrscraper scraper-api <url>`	Retrieve a known page as HTML, Markdown, a screenshot, or a combination.
`mrscraper web-search <query-or-url>`	Search Google from query text or a Google search URL.
`mrscraper status`	Show the account's subscription, token usage, and limits.

使用此 skill 进行设置、身份验证、命令选择、通用输出处理、账户状态检查和故障排除。页面检索和 Google 搜索请加载对应的专项 skill。

CLI 提供三个数据命令：

命令	用途
`mrscraper scraper-api <url>`	以 HTML、Markdown、屏幕截图或其组合形式检索已知页面。
`mrscraper web-search <query-or-url>`	根据查询文本或 Google 搜索 URL 搜索 Google。
`mrscraper status`	显示账户的订阅信息、token 用量和限额。

Step 1 — Verify or Install MrScraper

步骤 1 — 验证或安装 MrScraper

Check whether the CLI is available:

bash

command -v mrscraper && mrscraper --version

When an agent performs first-time setup, install the CLI and all three skills without starting an interactive authentication step:

bash

npx -y @mrscraper/cli@latest init --all --yes --skip-auth

The flags have separate purposes:

```
npx -y
```
approves npm package execution.
```
--yes
```
keeps bootstrap non-interactive.
```
--skip-auth
```
leaves login for the next step.
```
--all
```
installs skills for supported harnesses detected on the machine.

检查 CLI 是否可用：

bash

command -v mrscraper && mrscraper --version

当 Agent 首次进行设置时，应安装 CLI 和全部三个 skill，但不启动交互式身份验证步骤：

bash

npx -y @mrscraper/cli@latest init --all --yes --skip-auth

各个 flag 的用途各不相同：

```
npx -y
```
批准执行 npm 包。
```
--yes
```
使 bootstrap 保持非交互式。
```
--skip-auth
```
将登录留到下一步处理。
```
--all
```
为机器上检测到的所有受支持 harness 安装 skill。

Bootstrap parameters

Bootstrap 参数

Parameter	Default	Use
`--api-key <key>`	omitted	Save a supplied API key during bootstrap. Agents should use `--skip-auth` and handle login separately.
`--all`	detected harnesses	Install skills for every supported harness found on the machine.
`--agent <id>`	omitted	Install skills for one supported harness.
`-y, --yes`	off	Keep bootstrap non-interactive.
`--skip-install`	off	Skip global CLI installation.
`--skip-auth`	off	Leave authentication for a separate login step.
`--skip-skills`	off	Skip skill-pack installation.
`--dry-run`	off	Print planned actions without changing the system.

To target one harness, use its MrScraper ID:

Harness	ID
Claude Code	`claude-code`
Cursor	`cursor`
Codex	`codex`
Grok Build	`grok`
Hermes Agent	`hermes`
OpenCode	`opencode`
OpenClaw	`openclaw`
Pi	`pi`
Oh My Pi	`omp`

bash

npx -y @mrscraper/cli@latest init --agent codex --yes --skip-auth

Refresh the skill pack without reinstalling the CLI:

bash

mrscraper setup skills
mrscraper setup skills --agent codex
mrscraper setup skills --dry-run

setup skills

accepts

--all

for detected harnesses,

--agent <id>

for one harness, and

--dry-run

to preview the installation.

The bootstrap installs the CLI and skills. MCP is available separately at

https://mcp.mrscraper.com/mcp

with the same capabilities as the

scraperAPI

webSearch

, and

status

tools.

参数	默认值	用途
`--api-key <key>`	省略	在 bootstrap 期间保存提供的 API key。Agent 应使用 `--skip-auth` ，并单独处理登录。
`--all`	检测到的 harness	为机器上找到的每个受支持 harness 安装 skill。
`--agent <id>`	省略	为一个受支持的 harness 安装 skill。
`-y, --yes`	关闭	使 bootstrap 保持非交互式。
`--skip-install`	关闭	跳过全局 CLI 安装。
`--skip-auth`	关闭	将身份验证留待单独的登录步骤。
`--skip-skills`	关闭	跳过 skill 包安装。
`--dry-run`	关闭	打印计划执行的操作，而不更改系统。

若要指定一个 harness，请使用其 MrScraper ID：

Harness	ID
Claude Code	`claude-code`
Cursor	`cursor`
Codex	`codex`
Grok Build	`grok`
Hermes Agent	`hermes`
OpenCode	`opencode`
OpenClaw	`openclaw`
Pi	`pi`
Oh My Pi	`omp`

bash

npx -y @mrscraper/cli@latest init --agent codex --yes --skip-auth

无需重新安装 CLI 即可刷新 skill 包：

bash

mrscraper setup skills
mrscraper setup skills --agent codex
mrscraper setup skills --dry-run

setup skills

接受

--all

以处理检测到的 harness，接受

--agent <id>

以指定一个 harness，并接受

--dry-run

以预览安装过程。

Bootstrap 会安装 CLI 和 skill。MCP 可单独通过

https://mcp.mrscraper.com/mcp

使用，其功能与

scraperAPI

、

webSearch

和

status

工具相同。

Step 2 — Authenticate

步骤 2 — 身份验证

Inspect the available credential:

bash

mrscraper auth status --json

A configured credential reports

credential_configured: true

. This command reads local configuration only.

credential_configured: false

result means the CLI is not authenticated. On a local interactive machine, start browser login so the CLI can be used right away:

bash

mrscraper login

Keep the command running while the user approves the browser request. Browser login waits up to three minutes and stores the resulting API key under

~/.mrscraper/auth.json

, or under

MRSCRAPER_HOME

when configured.

For CI, containers, or headless automation, use

MRSCRAPER_API_KEY

. A human can also store a key outside the agent conversation:

bash

mrscraper login --api-key "<key>"

After credentials are configured, verify end-to-end access with the account check, which does not retrieve a page:

bash

mrscraper status --json

Treat a successful command as confirmation that the CLI can authenticate and reach the service. If it fails, report the error and do not claim setup is complete.

检查现有凭据：

bash

mrscraper auth status --json

已配置凭据时会报告

credential_configured: true

。此命令仅读取本地配置。

如果结果为

credential_configured: false

，则表示 CLI 尚未通过身份验证。在本地交互式机器上，启动浏览器登录，以便立即使用 CLI：

bash

mrscraper login

用户批准浏览器请求时，应保持该命令运行。浏览器登录最多等待三分钟，并将生成的 API key 存储在

~/.mrscraper/auth.json

下；如果配置了

MRSCRAPER_HOME

，则存储在该目录下。

对于 CI、容器或无头自动化，请使用

MRSCRAPER_API_KEY

。人工用户也可以在 Agent 对话之外存储 API key：

bash

mrscraper login --api-key "<key>"

配置凭据后，使用账户检查验证端到端访问能力；此操作不会检索页面：

bash

mrscraper status --json

命令成功即表示 CLI 能够完成身份验证并访问服务。如果失败，应报告错误，且不得声称设置已完成。

Login parameters

Login 参数

Parameter	Default	Use
`--api-key <key>`	omitted	Save an API key instead of opening browser login.
`--token <key>`	omitted	Deprecated alias for login's `--api-key` .
`--no-browser`	off	Prompt an interactive human for an API key.
`--no-open`	off	Print the browser URL while keeping the callback listener active.
`--timeout <seconds>`	`180`	Set the browser callback wait time.

Credential precedence for API commands is:

Command option
```
--token
```
;
Environment variable
```
MRSCRAPER_API_KEY
```
;
Environment variable
```
MRSCRAPER_API_TOKEN
```
; and
Saved credential
```
~/.mrscraper/auth.json
```
.

Never ask the user to paste an API key into chat, print credentials, or commit credential files. Use

mrscraper logout

to remove saved local credentials.

参数	默认值	用途
`--api-key <key>`	省略	保存 API key，而不是打开浏览器登录。
`--token <key>`	省略	Login 的 `--api-key` 的已弃用别名。
`--no-browser`	关闭	提示交互式用户输入 API key。
`--no-open`	关闭	打印浏览器 URL，同时保持回调监听器处于活动状态。
`--timeout <seconds>`	`180`	设置浏览器回调等待时间。

API 命令的凭据优先级为：

命令选项
```
--token
```
；
环境变量
```
MRSCRAPER_API_KEY
```
；
环境变量
```
MRSCRAPER_API_TOKEN
```
；以及
已保存的凭据
```
~/.mrscraper/auth.json
```
。

绝不要要求用户将 API key 粘贴到聊天中、打印凭据或提交凭据文件。使用

mrscraper logout

删除已保存的本地凭据。

Step 3 — Route the Request

步骤 3 — 路由请求

User outcome	Command or skill
Acquire and preserve a known public page for any downstream task	mrscraper-fetch with `mrscraper scraper-api`
Discover relevant pages from a Google query	mrscraper-serp with `mrscraper web-search` , then retrieve selected pages
Check the plan, token usage, or remaining tokens	`mrscraper status --json`

用户目标	命令或 skill
获取并保留一个已知的公共页面，供任何下游任务使用	mrscraper-fetch 与 `mrscraper scraper-api`
从 Google 查询中发现相关页面	mrscraper-serp 与 `mrscraper web-search` ，然后检索选定的页面
检查套餐、token 用量或剩余 token 数	`mrscraper status --json`

Retrieve first, extract locally

先检索，再在本地提取

The CLI returns raw page content. Produce summaries, tables, JSON, and other structured output from that content with local analysis or extraction code. The raw response preserves details for later questions, validation, and changes to the requested schema.

For many pages that share a layout:

Retrieve representative pages and inspect their content;
Understand the shared structure and required fields;
Define a stable output schema and one local extraction implementation;
Retrieve the remaining pages, in parallel when safe and proportional; and
Run the same extractor across all saved responses.

Request Markdown with

--markdown

when readable text is enough, and HTML when the extractor needs the page structure.

For discovery-first work, run

web-search

, select the relevant URLs, and retrieve the pages whose content will inform the answer.

The CLI does not create AI scrapers, rerun saved scrapers, or list stored results. Use the MrScraper dashboard at https://app.mrscraper.com for those.

CLI 返回原始页面内容。使用本地分析或提取代码，从该内容生成摘要、表格、JSON 和其他结构化输出。原始响应会保留相关细节，以便后续提问、验证以及按要求调整输出 schema。

对于许多采用相同布局的页面：

检索具有代表性的页面并检查其内容；
理解共享结构和所需字段；
定义稳定的输出 schema 和一套本地提取实现；
在安全且规模适当的情况下并行检索其余页面；以及
对所有已保存的响应运行同一个提取器。

如果可读文本已经足够，请使用

--markdown

请求 Markdown；如果提取器需要页面结构，请请求 HTML。

对于以发现为目标的工作，请先运行

web-search

，选择相关 URL，再检索其内容可用于回答问题的页面。

CLI 不会创建 AI scraper、重新运行已保存的 scraper 或列出已存储的结果。请使用 MrScraper 仪表板 https://app.mrscraper.com 完成这些操作。

Step 4 — Handle Output and Artifacts

步骤 4 — 处理输出和产物

Data commands print JSON to stdout:

json

{
  "status_code": 200,
  "data": {},
  "headers": {}
}

API failures exit nonzero and add

error

. Progress and diagnostics use stderr. Request

status --json

explicitly because an interactive terminal otherwise displays the account dashboard.

Save substantial artifacts under the current project's

./.mrscraper/

folder:

bash

mkdir -p ./.mrscraper
mrscraper scraper-api "https://www.scrapethissite.com/pages/simple/" \
  > ./.mrscraper/countries-page.json
mrscraper web-search "country population data" > ./.mrscraper/search.json

The project artifact folder

./.mrscraper/

is separate from the credential folder

~/.mrscraper/

. Keep project artifacts out of version control unless the user asks to commit them.

数据命令会将 JSON 打印到 stdout：

json

{
  "status_code": 200,
  "data": {},
  "headers": {}
}

API 失败时以非零状态退出，并添加

error

。进度和诊断信息使用 stderr。请显式请求

status --json

，否则在交互式终端中会显示账户仪表板。

将体积较大的产物保存在当前项目的

./.mrscraper/

文件夹下：

bash

mkdir -p ./.mrscraper
mrscraper scraper-api "https://www.scrapethissite.com/pages/simple/" \
  > ./.mrscraper/countries-page.json
mrscraper web-search "country population data" > ./.mrscraper/search.json

项目产物文件夹

./.mrscraper/

与凭据文件夹

~/.mrscraper/

相互独立。除非用户要求提交，否则不要将项目产物加入版本控制。

Step 5 — Review Account Usage

步骤 5 — 查看账户使用情况

Request machine-readable account status:

bash

mrscraper status --json

The response summarizes the subscription status, token limit, token usage, remaining tokens, usage percentage, rate limit, auto-renewal, renewal date, and the account's name, email, and verification state. It never includes the API key.

请求机器可读的账户状态：

bash

mrscraper status --json

响应会汇总订阅状态、token 限额、token 用量、剩余 token、使用百分比、速率限制、自动续费、续费日期，以及账户名称、邮箱和验证状态。其中绝不包含 API key。

Status parameters

Status 参数

Parameter	Default	Use
`--json`	automatic when piped	Print JSON. Agents should include it.
`--pretty`	automatic in a terminal	Print the account dashboard.
`--no-color`	off	Disable dashboard color.
`--token <key>`	configured credential	Override authentication.

Check remaining tokens before a large batch of page retrievals.

参数	默认值	用途
`--json`	通过管道传输时自动启用	打印 JSON。Agent 应包含此参数。
`--pretty`	在终端中自动启用	打印账户仪表板。
`--no-color`	关闭	禁用仪表板着色。
`--token <key>`	已配置的凭据	覆盖身份验证设置。

批量检索大量页面前，请检查剩余 token 数。

Step 6 — Troubleshoot

步骤 6 — 故障排除

Unauthorized or 401 — run
```
mrscraper login
```
in a local interactive session or verify
```
MRSCRAPER_API_KEY
```
in automation.
CLI missing — run the agent-safe
```
npx ... init
```
command from Step 1.
Skills missing — run
```
mrscraper setup skills --dry-run
```
, then target the current harness with
```
--agent <id>
```
.
Page blocked, incomplete, or missing dynamic content — load mrscraper-fetch and retry with page-loading options appropriate to the target.
Structured output is incomplete — inspect the saved raw content and improve the local extraction logic.
Search results are weak — load mrscraper-serp and refine the query, locale, or page.

Unknown option or command — run

mrscraper <command> --help

. The

fetch

scrape

serp

rerun

results

, and

result

commands were replaced by

scraper-api

web-search

, and

status

未授权或 401 — 在本地交互式会话中运行
```
mrscraper login
```
，或在自动化环境中验证
```
MRSCRAPER_API_KEY
```
。
缺少 CLI — 运行步骤 1 中对 Agent 安全的
```
npx ... init
```
命令。
缺少 Skill — 运行
```
mrscraper setup skills --dry-run
```
，然后使用
```
--agent <id>
```
定向当前 harness。
页面被阻止、内容不完整或缺少动态内容 — 加载 mrscraper-fetch，并使用适合目标页面的页面加载选项重试。
结构化输出不完整 — 检查已保存的原始内容，并改进本地提取逻辑。
搜索结果不理想 — 加载 mrscraper-serp，并优化查询、区域设置或页面。

未知选项或命令 — 运行

mrscraper <command> --help

。

fetch

、

scrape

、

serp

、

rerun

、

results

和

result

命令已分别被

scraper-api

、

web-search

和

status

取代。

Limits

限制

Use another tool for:

Clicking controls, completing forms, or authenticated browser sessions;
Parsing local PDFs, documents, spreadsheets, or other files;
Recurring monitoring, notifications, or scheduling.

Explain the boundary and continue with any supported portion of the task.

以下情况请使用其他工具：

点击控件、填写表单或使用需要身份验证的浏览器会话；
解析本地 PDF、文档、电子表格或其他文件；
定期监控、通知或调度。

请说明这些边界，并继续完成任务中受支持的部分。