如何在 Gemini CLI 中使用 MCP 设置 CAPTCHA 识别工具

摘要

• Gemini CLI 可以通过其 mcpServers 配置连接到本地 CAPTCHA 求解器。
• 将客户端指向 Python 环境的可执行文件以避免 PATH 问题。
• 在已批准的工作流中启用付费求解之前，先从工具发现开始。
• 已连接的 MCP 服务并不能证明账号一定能解出挑战，或浏览器表单已经完成。
• 文件夹信任和工具批准是两个独立的控制；应保持工具调用确认处于启用状态。

Gemini CLI 的 CAPTCHA 求解器设置从工具连接开始。如果你的终端代理用于维护浏览器测试或其他被允许的 Web 工作流，求解器应只出现在特定的 CAPTCHA 检查点。它不应替代普通的页面导航、应用验证，或你对代理可执行操作的决策。

CapSolver 暴露了一个本地 MCP 服务，Gemini CLI 可以发现它。本指南使用双方已文档化的接口将二者连接起来，说明如何检查连接，并展示求解工具在此之后应处于什么位置。可运行的示例面向 macOS 和 Linux。它不需要目标网站即可建立连接，也不假定 Gemini CLI 已经控制了浏览器。

CAPTCHA 求解器给 Gemini CLI 增加了什么？

CAPTCHA 求解器为 Gemini CLI 提供了一个可调用能力，用于处理已经由周边工作流识别并被允许处理的挑战。Gemini CLI 加载服务器配置并展现可用工具。MCP 进程提供工具定义并执行请求的操作。

对于测试自家应用的 QA 团队而言，浏览器测试在录入测试数据后可能会到达一个 CAPTCHA 小部件。这时求解器可以处理所支持的挑战，而测试仍然掌控表单输入以及对应用是否接受提交的断言。仅仅安装 MCP 服务并不会构建这些浏览器步骤。

Google 在其 MCP 服务器配置指南 中记录了客户端连接方法。CapSolver 则记录了相应的 MCP 服务与工具角色。这两个接口在本地 stdio 进程处汇合，因此初始发现阶段不需要额外的客户端适配器。

在连接工具之前你需要什么？

你需要一个受支持的 Node.js 运行时、Python、一个隔离的项目目录，以及官方的客户端和服务器包。该设置已经在 Node.js 24.16.0、Python 3.12.14、Gemini CLI 0.65.0 和 capsolver-mcp 0.1.3 下验证过。这些版本只是标明已测试的组合，而不是要求你长期固定使用。

官方的 Gemini CLI 安装说明 解释了客户端的前置条件。请使用 Python 3.10 或更新版本，以及一个被固定 Gemini 包所支持的 Node.js 版本。单独的环境可让你在不替换现有代理设置的前提下测试连接。

你需要理解两种不同的凭据。Gemini 的模型认证允许 CLI 生成响应。CapSolver 的 API 密钥 则授权诸如付费求解等账号操作。这两种凭据互不能替代。下面的连接检查既不会提交 CAPTCHA，也不会请求模型响应；后续的求解与对话式使用需要各自对应的账号配置。

安装本地服务器和客户端

在你打算测试连接的目录中安装官方包。于新的工作目录中创建一个 Python 环境并安装固定包：

python3 -m venv py
py/bin/python -m pip install capsolver-mcp==0.1.3
npm init -y
npm install --save-dev @google/gemini-cli@0.65.0

Python 安装会带入核心依赖。如果你稍后重现本指南，请检查安装的版本：依赖变更可能会在配置不变的情况下改变工具或输出。保留与项目绑定的环境，以便其它终端会话能可靠地找到它。

基础 MCP 包足以完成此次连接。面向浏览器的工具有额外依赖。你不需要这些工具就能建立初始连接。官方注册表安装演练 说明了已发布包及其安装方式。

在 Gemini CLI 中配置 MCP 服务器

配置 Gemini CLI 启动你刚才创建的环境中的 Python 解释器。将以下项合并到 ~/.gemini/settings.json 的现有用户设置中；保留无关设置和服务器。将可执行文件路径替换为你项目 py/bin/python 的完整路径。

{
  "mcpServers": {
    "capsolver": {
      "command": "/absolute/path/to/project/py/bin/python",
      "args": ["-m", "capsolver_mcp"],
      "env": {
        "CAPSOLVER_API_KEY": "${CAPSOLVER_API_KEY}"
      },
      "includeTools": ["get_supported_captchas", "solve_captcha"],
      "trust": false,
      "timeout": 60000
    }
  }
}

使用绝对解释器路径可以解决一个常见的配置问题：Shell 了解某个环境，但客户端却启动了另一个 Python。变量引用则避免在 JSON 文件中出现明文账号密钥。在请求账号操作前，请通过你常用的秘密管理流程提供真实密钥。

这个入门配置只暴露能力查询和基于 token 的求解工具。它将面向浏览器的工具置于允许列表之外，从而给你时间决定如何管理浏览器会话。超时是以毫秒为单位的客户端设置，而不是对 CAPTCHA 完成时间的承诺。

将文件夹信任与服务器信任分开

当当前文件夹是不受信任状态时，Gemini CLI 可能会禁用 MCP 服务器。对于你自有且已审查的项目，请按照 Google 的 受信任文件夹工作流 进行操作。请信任预期的项目范围，而不是修改无关文件夹。

服务器的 trust: false 设置有不同的作用：它保留下工具调用确认行为。一个被信任的工作目录并不意味着未来每一次工具调用都应自动批准。当你从连接诊断转向真实应用工作流时，要保持这种区分。

兑换你的 CapSolver 奖励码

立即提升你的自动化预算！
在为 CapSolver 账号充值时使用奖励码 CAP26，每次充值即可额外获得 5% 奖励 —— 无上限。
现在就到你的 CapSolver 控制台 进行兑换

在请求求解之前验证连接

在项目目录中使用 Gemini CLI 的 MCP 列表命令验证已配置的服务：

npx --no-install gemini mcp list

成功的检查结果显示 capsolver 服务器通过 stdio 连接且状态为 Connected。显示的命令包括解释器路径和 -m capsolver_mcp。你的绝对路径会不同。Disabled 结果通常指向配置或信任决策问题；连接失败则需要检查可执行文件及进程启动情况。

在配置好常规的 Gemini 认证后，通过客户端的 MCP 接口检查工具。一个有用的第一次请求是：只查询支持的 CAPTCHA 类型而不求解任何内容。对应工具是 get_supported_captchas；当你只需要能力检查时，不要替换成账号余额或求解请求。

验证边界是非常明确的：本地 Gemini CLI 连接针对真实 MCP 进程进行了测试。该检查并不声称发生了任何模型驱动的对话、付费挑战或浏览器表单完成。这些都是你选择构建的工作流所需的独立验收测试。

将求解器放在明确的浏览器检查点

应将求解操作放在已确认 CAPTCHA 检测之后、下一步应用级验证之前。对于由所有者控制的浏览器测试，预期顺序是：到达测试表单、识别支持的挑战、请求相应操作、应用文档化的结果，并检查应用的响应。

基于 token 的 solve_captcha 工具适用于已经掌握必要挑战参数、并拥有后续浏览器工作的应用。在发起调用之前，请阅读该工具的实际输入模式。过期的挑战或来自不同环境的 URL，并不会因为客户端已连接就变得有效。

CapSolver 也文档化了 detect_captchas 和 solve_on_page 这类基于浏览器的工具。它们需要浏览器附加组件和 Chromium，并且其会话行为必须适配你的应用。不要假定基于 URL 的工具会与由其他代理控制的无关浏览器共享 cookie 或活动页面。如果你需要操作自己程序已拥有的页面，请在选择其他集成方式之前，先审查 核心 SDK 的页面导向接口。

在首次上线时，选择一个经过批准的测试工作流，并写下它的完成信号。表单测试可能要求在提交已知测试数据后出现预期的确认状态。返回的 token 是关于求解器操作的证据；确认状态是关于应用的证据。在不记录凭据或完整 token 的前提下，将两者一并保存在测试结果中。

在排障时避免重复付费调用

在重新开始另一个挑战前，请先排查失败的阶段。当真正问题只是 Python 路径或被禁用的 MCP 服务时，重复付费求解是没有必要的。

• 如果进程无法启动，确认配置的解释器存在且已包含该包。
• 如果 Gemini 将服务列为已禁用，检查文件夹信任以及服务器是否被显式禁用。
• 如果服务已连接但缺少某个工具，对比允许列表和任何排除项与实际公布的名称。
• 如果账号操作失败，请检查密钥和账号要求，不要把发现过程当成认证证明。
• 如果结果返回了但表单没有完成，在调整 MCP 传输前先检查结果处理和应用验证。

每次只修改一项，并重复能确认该修改的最低成本检查。升级之后，在复用旧提示前重新发现工具名称和模式。相较于包含大量未打码请求的大日志，一份包含包版本、服务器名称和工具范围的小型配置记录通常更有价值。

从已连接的工具走向已测试的工作流

在本地连接和预期的浏览器交接都清晰之后，再转向真实求解。先从批准任务所需的最窄工具范围开始，然后独立验证应用的最终状态。CapSolver 可以提供 CAPTCHA 操作，而 Gemini CLI 则协助协调周边工作。

使用你的 CapSolver 控制台 为这次独立求解测试准备账号。在客户端或包变更后，将连接检查保留为一个快速诊断手段。

常见问题

问：完成此配置后，Gemini CLI 会自己解 CAPTCHA 吗？

不会。该配置只是连接了一个外部 MCP 工具提供方。周边工作流仍然需要有效输入、已批准的操作以及对应用结果的检查。

问：我需要 CapSolver API 密钥才能看到 Connected 状态吗？

经测试，本地连接在没有账号操作的情况下也能成功。付费求解需要有效密钥和满足适用的账号要求；Connected 状态并不校验这两者。

问：为什么在陌生文件夹里我的 MCP 服务器被禁用了？

Gemini CLI 的文件夹信任策略会在不受信任目录中抑制 MCP 服务器。请审查该文件夹，并按照客户端信任流程为预期范围授信。

问：为什么配置中只暴露了两个工具？

示例只允许能力查询和 token 求解工具。只有在审查过其他工具、其依赖以及它们在工作流中的适配度之后，再修改该列表。

问：页面求解工具会复用我现有的浏览器标签页吗？

不要想当然地认为会。请检查文档中的会话模型；基于 URL 的操作和由你的浏览器程序持有的页面对象是两种不同接口。

问：MCP 连接工作后，我应该测试什么？

用有效凭据测试一个获得授权的端到端工作流，并观测到可见的应用结果。将求解器状态与页面最终结果分别记录。