跳转到主要内容
获取令牌时遇到问题吗
联系支持

MCP

Model Context Protocol (MCP) 允许 AI 代理连接外部工具和服务。

CapMonster Cloud MCP 为代理提供处理 CAPTCHA 所需的工具。

CapMonster Cloud MCP 的工作原理

借助 MCP，AI 代理可以识别 CAPTCHA 类型和任务参数、访问 CapMonster Cloud 文档、创建任务并获取识别结果。代理的最终目标不仅是解决 CAPTCHA，还要将这一流程正确集成到用户项目中。

处理网页时，可以将 CapMonster Cloud MCP 与浏览器 MCP capmonster-mcp-patchright 配合使用：

AI 代理
├── capmonster → CapMonster Cloud API
└── patchright → 浏览器

capmonster 负责与 CapMonster Cloud 交互。patchright 打开页面，帮助识别 CAPTCHA 类型、获取其参数并应用已完成的解决结果。随后，代理会将已验证的流程集成到项目代码中。

SKILL.md 所覆盖的典型流程：

  1. 获取目标页面 URL。

  2. 识别 CAPTCHA 类型。

  3. 查看文档并确定必需参数。

  4. 从页面获取参数。

  5. 向 CapMonster Cloud 发送请求。

  6. 获取结果。

  7. 在页面上应用结果，并将该流程集成到用户代码中。

注意

仅在您有权执行自动化操作的资源上使用自动化，例如您自己的网站、测试环境或演示页面。

快速开始​

为 AI 代理复制 prompt

根据您的环境选择相应的 prompt — Python / PyPI 或 TypeScript / npm — 然后点击 复制 prompt。接着将其粘贴到 Claude Code、Codex 或其他 AI 代理中。代理会识别客户端和操作系统，配置 capmonster 和 patchright，并检查它们是否可以正常工作。

如果自动配置失败，请按照说明手动配置 MCP。

验证完成后，将目标页面 URL、项目文件以及 CAPTCHA 出现的条件提供给代理。代理不仅应在浏览器中验证解决方案，还应将可用的 CapMonster Cloud 流程集成到您的代码中。

配置期间的权限

代理可能会请求权限以安装依赖项、修改 MCP 配置、运行命令、访问网络或控制浏览器。请检查每个请求，并通过 Allow 或 Approve 确认预期操作。

在 Codex 中，可以使用 /permissions 命令检查或更改当前权限模式。

无需在每个任务之前重复发送 prompt。在当前会话中加载 SKILL.md 后，您可以继续提供新的 URL、CAPTCHA 出现条件和集成任务。

手动配置​

您可以通过 Desktop 应用、终端、IDE 或代码编辑器与代理配合使用。若要使用完整流程，建议同时连接两个服务器：capmonster 和 patchright。

请选择工作方式 — CLI 代理或 Desktop 应用。每个选项卡都包含所选方式的完整配置步骤。

步骤 1. 安装 AI 代理


您需要安装 AI 代理或其他支持 MCP 的应用。

如果代理已安装，请确认它可以正常启动并且系统能够找到该命令。

例如，对于 Claude Code：

claude --version

对于 Codex：

codex --version

如果找不到命令，请按照官方说明安装所选 AI 代理：Claude Code 或 Codex。

安装后，请确认代理能够正常启动并支持连接本地 MCP 服务器。

安装后找不到代理

如果终端或 IDE 无法识别已安装的代理，请完全关闭并重新打开终端和开发环境。已经运行的应用可能仍在使用旧的 PATH 值，因此在重启前无法识别新命令。

步骤 2. 安装 Node.js，并在需要时安装 uv


运行 MCP 服务器需要 npx，根据所选 CapMonster MCP 实现，还可能需要 uvx。

Node.js 和 npx

重要：

patchright 通过 npx 运行，因此无论选择哪种 CapMonster MCP 实现，都需要安装 Node.js。

检查安装：

node --version
npm --version
npx --version

如果这些命令不可用，请安装 Node.js。

npm 和 npx 通常会随 Node.js 一起安装，因此不需要单独安装 npx。

建议使用 Node.js 18 或更高版本。

uv 和 uvx

如果您计划使用 Python/PyPI 版本的 capmonster-mcp，还需要安装 uvx。

检查是否可用：

uvx --version

如果命令不可用，请安装 uv。

安装 uv 后，uvx 命令也会可用。

检查：

uv --version
uvx --version
注意

如果使用 TypeScript/npm 版本的 capmonster-mcp，则无需安装 uv 或 uvx。

步骤 3. 获取 API 密钥


capmonster 需要 CapMonster Cloud API 密钥。

该密钥通过以下环境变量传递给 MCP 服务器：

CM_API_KEY
步骤 4. 选择 CapMonster MCP 实现


capmonster-mcp 提供两种功能等效的实现。

此版本使用 npm 包 capmonster-mcp 和 npx。

使用以下命令运行 MCP 服务器：

npx -y capmonster-mcp

无需将 capmonster-mcp 安装为项目依赖。默认情况下，MCP 客户端可以通过 npx 或 uvx 直接运行已发布的包。

通过 npm 和 pip 安装包


默认情况下，无需预先安装 MCP 包：可以直接通过 npx 或 uvx 运行。如果希望提前安装，请使用以下任一方式。

CapMonster Cloud MCP

使用 npm 安装 capmonster-mcp：

npm i capmonster-mcp

可以使用以下命令检查安装：

npm list capmonster-mcp

安装后，使用 npx 运行 capmonster：

{
  "command": "npx",
  "args": ["capmonster-mcp"],
  "env": {
    "CM_API_KEY": "YOUR_API_KEY"
  }
}

Patchright MCP

如果您计划使用浏览器打开页面、获取 CAPTCHA 参数并应用解决结果，请安装 capmonster-mcp-patchright。源代码可在官方仓库中查看：

npm i capmonster-mcp-patchright

可以使用以下命令检查安装：

npm list capmonster-mcp-patchright

预先安装 capmonster-mcp-patchright 不是必需的。在下面的所有示例中，也可以直接使用以下命令运行：

npx -y capmonster-mcp-patchright

如果 npm 或 Python 包是在 MCP 客户端启动后安装的，请在安装完成后完全重启 MCP 客户端。


步骤 5. 配置 MCP 客户端


选择您使用的 CLI 客户端。

对于共享项目配置，请在项目根目录创建 .mcp.json 文件，并将 capmonster 和 patchright 添加到其中。

提示

这并不是唯一可用的位置。Claude Code 支持不同的配置作用域；用户级或项目级设置也可以存储在 .claude.json 中，或通过 Claude Code 命令添加。如果由代理配置 MCP，请允许它自动确定合适的作用域和配置文件。

{
  "mcpServers": {
    "capmonster": {
      "command": "npx",
      "args": ["-y", "capmonster-mcp"],
      "env": {
        "CM_API_KEY": "YOUR_API_KEY"
      }
    },
    "patchright": {
      "command": "npx",
      "args": ["-y", "capmonster-mcp-patchright"]
    }
  }
}

重启 Claude Code 后，使用 /mcp 命令检查连接。

将 YOUR_API_KEY 替换为您的 CapMonster Cloud API 密钥，然后重启 MCP 客户端。

步骤 6. 将 prompt 发送给代理


打开新的聊天或会话，并发送快速开始部分中的 prompt。验证完成后，提供页面 URL、项目文件以及 CAPTCHA 出现的条件。

配置期间，仅批准符合预期的权限请求。在当前会话中，无需在每个任务前重复发送 prompt。

可用工具​

连接 MCP 服务器后，相关工具会自动提供给 AI 代理。通常无需手动选择 — 代理会根据当前任务调用所需工具。

CapMonster Cloud​

capmonster-mcp 提供以下工具：

  • get_supported_tasks — 返回 CapMonster Cloud 支持的任务类型；
  • get_task_parameters(task_type) — 返回所选任务类型的参数和解决方案结构；
  • get_docs(url, offset, limit, section) — 加载 CapMonster Cloud 文档；
  • create_task(task) — 创建任务并返回 taskId；
  • get_task_result(task_id) — 单次检查任务状态；
  • get_task_result_wait(task_id, timeout_seconds, poll_interval_seconds) — 自动等待任务完成；
  • get_actual_user_agent() — 返回当前 Windows User-Agent；
  • get_balance() — 返回 CapMonster Cloud 账户余额。

Patchright​

capmonster-mcp-patchright 提供浏览器交互工具。代理通过 MCP 客户端访问这些工具，并自动选择所需操作。

当前工具列表可在官方仓库和 capmonster-mcp-patchright npm 包页面中查看。

故障排除​

让代理诊断问题

如果配置无法正常工作，请将错误信息发送给代理。代理可以检查运行环境、启动命令、用户和项目 MCP 配置，并建议或应用所需修复。

MCP 服务器无法启动

确认配置中的命令在 MCP 客户端运行的同一环境中可用：

node --version
npx --version
npx -y capmonster-mcp

如果命令启动后没有任何输出，这不一定表示出错：STDIO MCP 服务器正在等待客户端连接。可以使用 Ctrl+C 停止测试运行。

还请确认：

  • JSON 配置中没有注释、多余的尾随逗号或未闭合的括号；

  • mcpServers、command、args 和 env 字段名称拼写正确；

  • 修改配置后已完全重启 MCP 客户端；

  • 通过 npx 或 uvx 下载包时未被网络、代理、防病毒软件或企业策略阻止。

安装包后找不到 capmonster-mcp 命令

预先安装的 CLI 命令必须存在于启动 MCP 客户端的进程 PATH 中。

检查命令位置：

where.exe capmonster-mcp

如果终端可以找到该命令，但 Desktop 应用无法找到，请完全关闭并重新打开应用。如有必要，请在 command 字段中指定可执行文件的完整路径。

capmonster 或 patchright 工具未显示

请让代理检查当前会话从何处加载 MCP 配置。具体位置取决于客户端、配置作用域以及服务器的连接方式：

  • 在 Claude Code 中，服务器可以在项目级或用户级配置；配置可能存储在 .mcp.json、.claude.json 中，也可能通过 Claude Code 命令管理；

  • Claude Desktop 使用 claude_desktop_config.json；

  • Codex 使用 ~/.codex/config.toml、%USERPROFILE%\.codex\config.toml 或项目级 .codex/config.toml；

  • 在 ChatGPT Desktop 中，也可以通过 MCP 设置添加本地服务器。

修复配置后，请完全重启客户端并打开新会话。在 Claude Code 中，可以使用 /mcp 检查连接；在 Codex 中，可以使用 /mcp 或 codex mcp list。

get_balance 返回错误

请让代理检查 capmonster 配置。通常需要确认：

  • CM_API_KEY 变量中包含有效的 CapMonster Cloud API 密钥；

  • 已将占位值 YOUR_API_KEY 替换为实际密钥；

  • 密钥传递在 capmonster 服务器的 env 配置块中，而不是 patchright 中。

更改密钥后，请重启 MCP 客户端。随后，代理可以再次检查连接和余额。

如果余额为零，请先充值再创建任务。

get_docs 无法加载文档

请让代理检查 MCP 客户端是否可以访问 https://docs.capmonster.cloud/，以及是否能够加载以下文件：

https://docs.capmonster.cloud/llms.txt

如果文档暂时不可用，或者需要进一步验证任务参数，代理可以使用 API 规范：

https://api.capmonster.cloud/docs/swagger-ui/spec.js
patchright 无法打开页面

检查 node、npx 和启动命令：

npx -y capmonster-mcp-patchright

如果页面需要代理、User-Agent 或 locale，请将这些参数提供给代理。代理可以在通过 patchright 启动浏览器时使用这些参数。

任务返回错误或网站拒绝解决结果

请将错误信息和 CAPTCHA 出现条件提供给代理。进行诊断时，代理可以：

  1. 检查是否使用了受支持的任务类型；

  2. 获取当前参数和解决方案结构；

  3. 打开所选 CAPTCHA 类型的文档；

  4. 在重新加载页面或再次触发 CAPTCHA 后重新获取动态参数；

  5. 对于与会话绑定的 CAPTCHA，检查 User-Agent、代理、cookies、请求头和 Client Hints 是否保持一致；

  6. 确认结果以该 CAPTCHA 类型所要求的格式进行应用。

不要使用已过期的 challenge、token、data、blob 或其他一次性参数。

ERROR_INVALID_TASK 通常表示参数无效或已过期。ERROR_CAPTCHA_UNSOLVABLE 可能是临时错误 — 代理可以检查输入数据并创建新任务。

常见问题​

需要手动选择和调用 MCP 工具吗？

不需要。连接 MCP 服务器后，工具会自动提供给 AI 代理。代理会根据当前任务自行选择并调用所需工具。

必须连接两个 MCP 服务器吗？

不必须。如果 CAPTCHA 参数已知，并且不需要浏览器交互，可以单独使用 capmonster。当代理需要打开页面、获取 CAPTCHA 参数或应用解决结果时，则需要 patchright。

应该选择哪种实现：npm 还是 Python？

两种 capmonster-mcp 实现提供相同的工具。请选择与您的环境匹配的方式：

  • npm — 如果已经安装 Node.js 和 npx；

  • Python — 如果使用 Python 3.11 或更高版本，并且已安装 uvx。

无论哪种方式，patchright 都需要 Node.js 和 npx。

API 密钥应该存储在哪里？

通过 capmonster 服务器配置中的 CM_API_KEY 环境变量传递 API 密钥。不要将密钥添加到 prompt、聊天消息、代码示例或公共仓库中。

如果配置文件中包含真实密钥，请将其排除在 Git 之外，或使用 MCP 客户端支持的安全密钥存储机制。

每次解决 CAPTCHA 前都需要发送 prompt 吗？

不需要。完成配置后，在当前会话中只需提供新的 URL、CAPTCHA 出现条件和集成任务即可。

在新会话中，如果代理不会保留已加载的说明和环境检查结果，建议再次发送 prompt。

如何检查支持哪些 CAPTCHA 类型？

请让代理识别支持的 CAPTCHA 类型。代理可以使用 get_supported_tasks，对于具体任务，还可以使用 get_task_parameters(task_type) 以及通过 get_docs 获取文档。

需要在 MCP 配置中设置代理吗？

不一定。如果浏览器需要代理，请将代理参数提供给 AI 代理 — 它可以在不修改 MCP 配置的情况下启动浏览器并使用这些参数。

如果所选 CAPTCHA 类型要求使用自有代理，代理还必须在 CapMonster Cloud 任务中传递相应参数。对于与 IP 地址或会话绑定的 CAPTCHA，浏览器和任务必须使用同一个代理。

这篇文章有帮助吗？
查看 AI CAPTCHA 求解器的价格