如何使用 CapSolver MCP 服务器：AI 代理设置指南

TL;DR

• CapSolver MCP 服务器公开了五个已记录的工具：solve_captcha、detect_captchas、solve_on_page、get_balance 和 get_supported_captchas。
• 在安装 capsolver-mcp 之前，请先安装 capsolver-core，然后配置一个 MCP 客户端，通过环境中的 API 密钥启动 capsolver-mcp 命令。
• 浏览器工具需要浏览器附加组件和 Chromium；当已知 CAPTCHA 类型、页面 URL 和站点密钥时，令牌模式可以在无需浏览器的情况下运行。
• 生产代理需要经过批准的主机规则、一次绑定的恢复尝试、脱敏日志和应用级成功检查。

简介

使用 CapSolver MCP 服务器最安全的方法是将 CAPTCHA 处理视为一种狭窄的基础设施工具，而不是代理的新权威来源。CapSolver 提供了官方的 capsolver-mcp 服务，它封装了 capsolver-core，并让兼容的 AI 客户端发现已记录的 CAPTCHA 工具。然后代理可以在授权的浏览器工作流中恢复 reCAPTCHA v2、reCAPTCHA v3（包括企业版）或 Cloudflare Turnstile 中断。您的应用程序仍然拥有范围、凭证、重试限制和最终的业务断言。本指南展示了实际的安装和 JSON 配置，解释了每个工具和输出边界，并定义了合法、合理、负责任使用的停止条件。它不授权访问私人、受限、敏感或未经授权的数据。

了解 CapSolver 的三个层

在决定如何使用 CapSolver MCP 服务器之前，请区分产品层。CapSolver for AI Agents 概述 描述了恢复层架构。capsolver-core 执行检测和解决，capsolver-agent 将这些方法适配为代理可调用的模式，capsolver-mcp 通过 MCP 发布相同的功能。

核心 SDK API 记录了 create_capsolver、detect、get_captcha_info、solve 和 solve_on_page。代理工具适配器 记录了 get_all_tools 和 create_executor。MCP 服务指南 是安装、传输、配置和五个 MCP 工具的权威来源。

在客户端已支持 MCP 时选择 MCP

对于 Claude Desktop、Cursor、Cline、VS Code 客户端或其他兼容主机，使用 CapSolver MCP 服务器。当您自己编写函数调用循环时，请使用 capsolver-agent。当 Playwright 或服务拥有完整的控制流且无需模型的工具模式时，请使用 capsolver-core。这种区分可以防止重复的适配器，并使如何使用 CapSolver MCP 服务器更易于维护。

安装官方包

官方顺序首先安装核心引擎，然后安装 MCP 包装器：

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-mcp.git

对于浏览器检测和 solve_on_page，请安装浏览器附加组件和 Chromium：

pip install "capsolver-mcp[browser] @ git+https://github.com/capsolver-ai/capsolver-mcp.git"
playwright install chromium

这些命令是使用 CapSolver MCP 服务器的验证输入。成功的输出是一个可执行的 capsolver-mcp 命令。如果安装解析为非官方包名称、命令缺失或浏览器模式部署中 Chromium 不可用，请停止。

配置 MCP 客户端

官方的 stdio 配置简洁且适用于许多本地 MCP 客户端：

{
  "mcpServers": {
    "capsolver": {
      "command": "capsolver-mcp",
      "env": {
        "CAPSOLVER_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

请将真实密钥保存在密钥管理器或客户端环境中，而不是源代码控制中。输入是命令和环境。输出是可检查工具列表的连接服务器。停止条件是启动失败、意外的可执行路径或不完整的注册表。MCP 工具规范 解释了为什么客户端应在调用前发现和验证工具模式。

验证确切的工具名称

重新加载客户端后，确认所有五个名称：solve_captcha、detect_captchas、solve_on_page、get_balance 和 get_supported_captchas。在 MCP 服务器上修复 CAPTCHA 错误 的文章提供了有用的诊断路径，而 MCP 代理检查点恢复 解释了为什么恢复必须保持有限。

领取您的 CapSolver 奖励代码

立即提升您的自动化预算！
在充值 CapSolver 账户时使用奖励代码 CAP26，每次充值可获得额外 5% 奖励——无限制。
现在在您的 CapSolver 仪表板 中领取

定义输入、输出和停止条件

在令牌模式下，代理提供支持的 CAPTCHA 类型、授权页面 URL 和公共站点密钥；solve_captcha 通过 MCP 工具结果返回解决方案。在浏览器模式下，detect_captchas 列出检测到的类型，solve_on_page 执行记录的检测、解决和填充。get_balance 报告余额信息，get_supported_captchas 报告当前注册表。

不要从非错误工具响应中推断成功。应用程序必须验证同一浏览器会话中预期路线、表单状态或测试断言是否已更改。在一次自主尝试后、主机名更改、第二次检查点、授权过期、不支持的 CAPTCHA 类型或模糊页面状态后停止使用 CapSolver MCP 服务器。

MCP CAPTCHA 设置指南 帮助将配置连接到实际工具发现。对于 reCAPTCHA 特定的 MCP 行为，Cursor reCAPTCHA v2 示例 展示了窄客户端集成与通用服务器部署的差异。

添加生产防护措施

如何使用 CapSolver MCP 服务器的生产实现应仅允许批准的主机和声明的操作。将 Cookie 和凭证保留在模型消息之外。记录请求标识符、工具名称、终端状态和脱敏错误代码，而不是原始令牌。OWASP 日志指南 支持隐私意识的事件设计，NIST AI 风险管理框架 支持可问责的控制。

测试缺失密钥、缺失浏览器依赖项、不完整的工具发现、不支持的类型、未更改的页面状态和重复挑战。每个负面情况应返回终端审查状态，而不是另一个自主调用。

结论

使用 CapSolver MCP 服务器的实用方法是直接的：安装 capsolver-core 和 capsolver-mcp，配置官方命令，验证所有五个工具，并在每个调用前放置严格的授权门禁。将应用成功视为结果，将工具完成视为证据。运营授权 AI 代理工作流的团队可以将 CapSolver 视为 CAPTCHA 基础设施层。

常见问题

CapSolver MCP 服务器是否支持所有 CapSolver 代理任务类型？

不。当前的 AI 代理文档将此层限制为 reCAPTCHA v2、reCAPTCHA v3（包括企业版）和 Cloudflare Turnstile。在运行时检查 get_supported_captchas。

MCP 客户端应启动哪个命令？

使用官方的 capsolver-mcp 可执行文件，或在可执行文件不在客户端的 PATH 中时，使用环境中的 Python 启动已安装的模块。

使用 CapSolver MCP 服务器何时需要 Playwright？

浏览器检测和 solve_on_page 需要浏览器附加组件和 Chromium。当页面参数已知时，令牌模式不需要浏览器。

AI 代理在 CAPTCHA 调用后应何时停止？

在作用域更改、不支持的类型、缺少浏览器上下文、重复挑战、授权过期或一次尝试后应用状态未更改时停止。