如何在 Qwen Code 中设置 CAPTCHA Solver MCP 工具

摘要

• Qwen Code 可以将官方 CapSolver MCP 服务作为本地 stdio 进程进行连接。
• 在项目的 .qwen/settings.json 中配置该服务器，并使用安装相关依赖的 Python 环境中的可执行文件。
• 审核并批准项目服务器后，运行 qwen mcp list 检查连接情况。
• 成功连接服务器意味着工具可用，但并不代表付费验证码请求或浏览器提交一定成功。
• 使用令牌类工具处理显式的验证码参数，使用浏览器类工具处理由该服务管理的页面。不同 MCP 服务器不会自动共享浏览器标签页。

Qwen Code 是一个在终端中运行的开源编码智能体。开发者可以使用它处理应用代码并调用已连接的工具。当一个已授权的浏览器工作流遇到验证码时，仅靠一个代码模型并不能提供验证码解答。解题服务需要相关挑战的输入信息以及一个明确的结果回传位置。

CapSolver 通过其官方 MCP 服务对外提供这些能力。本指南说明如何将该服务连接到 Qwen Code、检查客户端是否可以访问它，并解释如何选择合适的工具。本文中的连接示例不要求模型即兴编写 Python 代码或凭空构造 API 请求载荷。

Qwen Code 集成能带来什么

该集成让 Qwen Code 可以访问一个单独的服务，该服务实现了与验证码相关的工具。Qwen Code 仍然是负责发现工具并发起操作请求的客户端；服务端则负责执行已文档化的解题操作。

官方 Qwen Code 项目 将该产品描述为一个终端编码智能体。MCP 则通过由服务器提供的能力扩展该环境。安装验证码服务器并不会让所有编码任务都变成浏览器任务，普通代码编辑也不需要验证码解题服务。

一个典型场景是：开发者在检查一个被允许的浏览器工作流时，下一步操作被验证码阻挡。开发者可以检查该挑战、选择一个受支持的操作，并让解题结果保持与该页面关联。这个范围要比“让整个网站都能被访问”窄得多。

如果 MCP 是你工作流中的新事物，那么客户端与一次 API 调用 的区别非常重要：工具描述只是声明一种操作，而真正的调用才实际执行它。连接状态代表“可用性”，而不是对所有已声明操作的“执行成功”担保。

准备客户端和 Python 环境

在编辑项目配置前，先准备好 Qwen Code 以及包含官方服务器的 Python 环境。

本文描述的连接示例使用 Qwen Code 0.26.1，搭配 capsolver-core 0.1.1 和 capsolver-mcp 0.1.3。Qwen Code 的包要求 Node.js 22 或更高版本。如果尚无 qwen 命令，请参考其官方安装说明进行安装。

在你打算让 Qwen Code 启动的那个 Python 环境中安装解题相关包：

python -m pip install capsolver-core==0.1.1 capsolver-mcp==0.1.3

官方 MCP 安装指南 也说明了浏览器扩展和 Chromium 的安装。这些依赖是浏览器端检测与页面解题所必需的，但与建立 stdio 连接是分离的。

有效的 CapSolver API 密钥和足够的账户余额是付费解题的前提条件。在 Qwen Code 中访问模型，则是进行对话式工具调用的另一项独立前提。下面的连接检查只测试服务器启动与连接本身；不会提交付费解题，也不会运行由模型驱动的任务。

请将账户密钥保存在用于启动 Qwen Code 的运行环境中。不要把真实密钥值粘贴到被跟踪的项目配置文件、文章、Issue、截图或共享对话记录中。

在项目中配置服务器

在项目根目录的 .qwen/settings.json 文件中，为 mcpServers 对象添加一个 capsolver 条目。

Qwen Code 在其 MCP 配置参考文档 中说明了项目配置及环境变量替换机制。将新的服务器条目“合并”进已有配置，而不是覆盖其他服务器或项目偏好设置。

{
  "mcpServers": {
    "capsolver": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["-m", "capsolver_mcp"],
      "env": {
        "CAPSOLVER_API_KEY": "${CAPSOLVER_API_KEY}"
      },
      "trust": false
    }
  }
}

将可执行文件路径替换成你已安装环境中实际的 Python 路径。使用绝对路径可以防止终端、编辑器或服务启动器通过自己的搜索路径找到另一个 Python 安装。要保留虚拟环境自身的路径；如果将其解析为基础解释器的真实路径，可能会选择一个未安装所需包的解释器。

占位符是一个环境变量引用，而不是 API 密钥本身。该变量必须在启动 Qwen Code 时存在于进程环境中。在一个终端中设置的密钥，并不会自动对从其他位置启动的客户端可见。

此配置使用 stdio：Qwen Code 将以本地进程的形式启动该 Python 模块。不需要公开的 HTTP 端点、暴露的端口，也不需要内容发布工作流中 CMS MCP 的凭据。

兑换你的 CapSolver 奖励码

立刻提升你的自动化预算！
充值 CapSolver 账户时使用奖励码 CAP26，每次充值都可额外获得 5% 奖励金——没有上限。
现在就去你的 CapSolver 控制台 兑换吧。

批准并验证真实连接

在审核完项目服务器配置后，批准该服务器，然后在同一项目目录中检查连接状态。

qwen mcp approve capsolver
qwen mcp list

在本文测试的客户端版本中，一个未批准的项目条目会显示为等待批准。批准之后，服务器才能建立连接。最有用的信号是 capsolver 条目显示为已连接；该行同时会标明所用可执行文件和传输方式。

“批准”（approve）与 trust 字段的作用不同。批准一个已审核的服务器，是允许它建立连接。而保持 trust 为 false 则可以保留正常的工具调用确认行为。不要仅仅为了掩盖配置问题而修改这一设置。

如果连接失败，先检查可执行文件路径，再确认同一 Python 环境是否可以导入安装的相关包。检查你修改配置的是否是当前打开的那个项目。Qwen 的 设置参考 说明了配置来源；其他位置的重复条目可能会让排障变得更复杂。

成功连接但未设置解题密钥，仍然不能说明账户已经可用。连接检查和可计费操作涉及系统中不同的部分。

根据验证码步骤选择合适工具

根据当前工作流中已有的信息及浏览器状态选择工具。

官方服务提供了 get_supported_captchas、get_balance、detect_captchas、solve_captcha 和 solve_on_page。当你需要确认已安装服务的能力名称时，可先查看支持类型列表。排查账户状态时，再单独检查余额。

当工作流中已经有文档化的验证码类型和站点参数时，使用 solve_captcha。它的结果仍然需要由发起请求的应用来消费。对于基于令牌的任务而言，收到令牌并不代表表单已经提交，也不能证明网站已经接受该请求。

浏览器类工具只能在其已文档化的浏览器设置下使用。detect_captchas 会检查某个页面 URL。solve_on_page 则在服务端的浏览器工作流中组合检测、解题和回填操作。二者的名称都并未承诺可以访问另一个 MCP 服务器所属的浏览器标签页。

在初步对话式检查时，可以让 Qwen Code 通过已配置的服务器列出当前支持的验证码类型。对于已授权页面上的任务，要精确说明页面以及被允许的操作，然后在执行前审查所选工具及其参数。避免下达那种“持续尝试直到网站放行”的开放式指令。

明确处理浏览器接力（handoff）

浏览器接力必须保留任务所需的上下文。只有 URL 可能无法还原通过一系列交互才到达的页面。

如果你现有的浏览器自动化正在控制一个实时页面，请先判断你需要的是该工作流中的令牌，还是与该页面的 SDK 集成。不要假设添加两个 MCP 服务器就能合并它们的会话、Cookie、标签页或 JavaScript 状态。

Core SDK 集成指南 描述了直接的浏览器集成。当应用需要保留已有页面对象时，这可能是更合适的方案。令牌与 Cookie 的差异说明 也有助于区分解题服务返回的工件与浏览器会话的广义状态。

在认为工作流“完成”之前，请检查应用的实际结果：预期的表单是否被接受？被允许访问的页面是否进入了预期状态？“服务器已连接”“组件已检测到”“应用请求被接受”是三个不同的里程碑。

使用 CapSolver 构建可靠的自动化工作流

连接官方服务，查看所提供的工具，并从一个与你工作流中验证码相匹配的、边界清晰的操作开始。CapSolver 可以提供文档化的解题步骤，而 Qwen Code 仍然负责在你所批准的任务范围内选择并调用这些工具。

常见问题

问：Qwen Code 默认包含验证码解题功能吗？

不包含。本文是在其中添加官方 CapSolver MCP 服务，作为一个独立的工具提供方。Qwen Code 的模型与解题账户是两个独立组件。

问：为什么服务器显示为等待批准（pending approval）？

项目中的 MCP 配置条目可能需要批准后，Qwen Code 才会连接。请先审核其命令与环境配置，然后使用你所安装客户端版本支持的批准命令进行批准。

问：我能在不为验证码付费的情况下测试连接吗？

可以。服务器连接可以独立于付费解题来检查。已连接状态并不能验证你的账户余额、付费任务是否执行，或网站是否接受了解题结果。

问：该服务会复用我在其他 MCP 中打开的浏览器标签页吗？

不要假设会。不同服务器拥有彼此独立的浏览器工作流，除非有已文档化的集成显式将其打通。当你需要保留现有页面时，请选择令牌模式或直接 SDK 集成。

问：为什么安装之后仍然看不到浏览器类工具？

请检查官方 MCP 指南中的浏览器扩展与 Chromium 先决条件。同时排查客户端侧是否有工具过滤，以及预期的服务器条目是否已成功连接。

问：这个配置能处理所有页面上的所有验证码吗？

不能。请以当前支持类型列表及任务文档为准，并将操作限制在你有权限自动化的页面和工作流之中。已声明的工具能力并不保证能在任意页面上取得成功。