如何在 Goose 中添加 CAPTCHA 解题 MCP 扩展

摘要

• 使用官方 Python 服务器，将 CAPTCHA 求解器作为本地 MCP 扩展添加到 Goose 中。
• 将包含该服务器的 Python 环境的绝对路径告诉 Goose；安装在其他环境中的包不会被自动找到。
• 先只开放 get_supported_captchas 这一项工具，然后在 Goose 的工具菜单中检查以确认已成功连接。
• 当扩展名为 capsolver 时，Goose 会将选中的工具显示为 capsolver__get_supported_captchas。
• 扩展连接正常并不代表付费 CAPTCHA 任务或浏览器工作流已经成功执行。

Goose 是为开发者设计的开源 AI agent，可以通过 MCP 扩展调用外部工具。Goose 的 CAPTCHA 求解扩展增加了一项特定能力：让你现有的 agent 能访问求解器已文档化的操作。当你在为一个已授权的浏览器任务添加 CAPTCHA 处理能力，并需要确认 Goose 确实能找到所需工具时，这会非常有用。

CapSolver 提供了下文所使用的 MCP 服务器。本指南重点讲解安装、Goose 配置以及一个不会提交 CAPTCHA 的连接检查。同时说明在使用求解工具之前，你还必须额外完成哪些准备。你可以在不编写自定义 MCP 服务器或框架适配器的情况下完成整个设置。

Goose 的 CAPTCHA 扩展能带来什么？

Goose 的 CAPTCHA 扩展通过 Goose 已有的 MCP 支持暴露官方服务器的工具。Goose 仍然是 agent 客户端；Python 进程则提供 CAPTCHA 操作。Goose 扩展指南支持自定义 MCP 服务器，即便它们没有出现在扩展目录中。

如果你已经连接了一个浏览器工具，这一点的区别就很重要。浏览器工具控制自己的浏览器会话，而求解工具会执行其输入 schema 所描述的操作。安装求解器并不会自动将其附着到某个已打开的 Chrome 标签页上，也不会从其他扩展中接管页面状态。

官方 MCP 工具参考区分了以 token 为导向的求解方式和基于 URL 的浏览器工具。请选择与你现有工作流匹配的接口。在首次设置时，先使用 supported-types 查询：它可以检查服务器声明的能力，而不会创建付费的挑战任务。

准备 Goose 和 Python 服务器

准备好已安装的 Goose CLI，以及一个单独用于 MCP 服务器的 Python 环境。请使用 Python 3.10 或更新版本；所固定的 MCP 包需要该版本或以上。下述设置在 macOS 上使用 Goose 1.55.0、Python 3.12.14、capsolver-mcp 0.1.3 和 capsolver-core 0.1.1 进行过验证。这些版本仅标明已测试的组合，并不保证所有后续版本的行为完全一致。

如果你刚接触 Goose，请按照其针对你操作系统的官方安装说明进行安装并配置模型提供商。稍后使用的工具权限检查需要 Goose 已选定提供商与模型。提供商配置独立于 CapSolver 账号密钥。

在一个环境中安装求解器

在 macOS 或 Linux 上的新项目目录中运行：

python3 -m venv py
py/bin/python -m pip install capsolver-core==0.1.1 capsolver-mcp==0.1.3
py/bin/python -c 'import sys; print(sys.executable)'

保留最后一条命令打印出的解释器路径。Goose 会直接启动该解释器，这样服务器就能使用你刚安装的那些包。这可以避免一个常见错误：终端使用了虚拟环境，但 agent 却启动了另一套 Python 安装。

对于本文的连接检查而言，这一基础安装已经足够。服务器的基于浏览器的工具还有额外依赖；仅安装基础包并不会为 Chromium 做好准备。仅为了检查 supported-types 工具，无需安装浏览器。

找到 Goose 实际使用的配置文件

运行以下命令定位你的 Goose 配置：

goose info

使用你的安装所显示的配置路径。默认位置以及任何配置中的路径覆盖都可能不同，因此依赖实际运行的 CLI 所返回的结果要比猜测位置更可靠。编辑文件时请保留你现有的提供商设置和其他扩展。

将 CAPTCHA 服务器添加到 Goose 配置中

在 Goose 的 YAML 配置中，将服务器添加到现有的 extensions 映射下。不要在已包含一个顶层 extensions 键的文件中再粘贴第二个顶层 extensions。

将下面示例中的解释器路径替换为安装步骤中打印出的绝对路径。以下是一个配置模板；在初次发现检查中，路径是你唯一需要按本机情况替换的值。

extensions:
  capsolver:
    name: capsolver
    type: stdio
    enabled: true
    cmd: /absolute/path/to/project/py/bin/python
    args: ["-m", "capsolver_mcp"]
    envs:
      CAPSOLVER_API_KEY: ""
    env_keys: []
    timeout: 60
    available_tools: ["get_supported_captchas"]

对于这次初始检查来说，账号密钥留空是有意为之。supported-types 工具不需要发起付费求解请求。空值并不是可用于付费操作的有效凭证。

Goose 配置参考对 stdio、cmd、args 和 available_tools 有详细说明。这里，stdio 表示 Goose 启动本地进程，并通过其标准输入输出交换 MCP 消息。你无需暴露任何网络端口。

理解工具过滤器

available_tools 项使该扩展只暴露 get_supported_captchas 这一工具。在 Goose 中，空列表表示所有工具，因此如果你删除工具名但保留 []，就会扩大可用工具的范围。

在确认解释器和服务器能正确启动前，请保持初始过滤范围尽量窄。一旦连接已正常工作，再将列表调整为工作流所需的特定操作。请使用官方参考中的远程工具名称，而不要根据其他客户端中的标签去猜。

timeout 以秒为单位。示例中的 60 秒是为这次设置检查所使用的配置值，并不是测得的 CAPTCHA 求解时间，也不是服务保证。

验证 Goose 能发现 CAPTCHA 工具

在让 agent 执行浏览器任务之前，先通过 Goose 的工具权限菜单验证工具发现是否正常。运行：

goose configure

依次选择 goose settings → Tool Permission → capsolver。Goose 会连接到已配置的扩展并列出其工具。在上述过滤设置下，菜单中应该包含 capsolver__get_supported_captchas，其说明为列出该实例支持的 CAPTCHA 类型。

该具命名空间的条目确实出现在为本指南进行的 Goose 连接检查中。双下划线将配置的扩展名与服务器的工具名区分开来。YAML 过滤器使用 get_supported_captchas；而 Goose 菜单中则显示 capsolver__get_supported_captchas。

在查看完该条目后，你可以在工具选择菜单中取消操作。查看已发现的工具并不要求你更改其权限。Goose 的工具权限控制允许你单独决定 agent 可以如何调用它。

如果工具缺失，请先在添加长提示或目标 URL 之前修复发现问题。模型无法调用客户端尚未加载的工具。此外，在修改扩展设置后请重新启动或重新连接；只对新会话生效的配置可能不会改变现有对话中的工具。

兑换你的 CapSolver 奖励码

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

从工具发现转向实际 CAPTCHA 任务

只有在选定操作并准备好其文档规定的输入之后，才开始 CAPTCHA 任务。连接检查只证明 Goose 能加载真实的 MCP 服务器并发现被过滤出的工具。它不会测试模型选择、付费求解或页面完成情况。

在已有可用模型提供商的前提下，一个有用的下一条请求是：“使用 CAPTCHA 扩展的 supported-types 工具，并总结其返回的能力。不要提交任何求解任务。”这只是建议性的后续提示，并不代表本指南在撰写过程中真的执行过一次由模型驱动的调用。请检查工具调用及其返回数据，而不要只接受对话式回答。

对于以 token 为导向的工作流，当你准备好提供受支持的 CAPTCHA 类型和所需站点参数时，启用 solve_captcha。通过扩展的环境设置配置有效账号密钥，并保留对工具调用的常规审批控制。请务必将真实凭证排除在共享配置示例和源码管理之外。

对于 detect_captchas 或 solve_on_page，请先按照官方工具参考中的 browser-extra 和 Chromium 安装步骤操作。这些操作接受页面 URL；它们不会自动复用属于另一个 Goose 扩展的浏览器会话。对于表单状态已发生变化的页面，这种会话边界尤其重要。

当你的应用必须与自己已经控制的页面对象协同时，可以进一步研究核心 SDK 的页面接口。请基于这一具体需求进行选择，而不要假定所有 MCP 浏览器工具都共享一个标签页。

API 调用与应用动作完成是两个不同的结果。当你最终测试一个已授权的 CAPTCHA 工作流时，请同时检查求解器响应和预期的页面结果。将本文的设置检查与应用层面的验收测试分开进行。

解决常见 Goose 扩展设置问题

请在出错步骤定位问题：解释器启动、包导入、工具发现或后续任务调用。下面这些检查通常有助于找出故障位置。

不要为了修正导入错误而用任意 HTTP 端点替换一个本地已正常使用 stdio 的配置。关键在于启动命令和包所在环境。官方注册表安装教程提供了更多关于定位和启动支持包的背景信息。

在寻求帮助时，请记录 Goose 版本、Python 版本、包版本以及失败的阶段。经过脱敏的启动路径和报错信息，比包含 API 密钥的截图要有用得多。不要为了确认扩展是否已安装而反复提交付费任务。

让下一步紧扣你的浏览器任务

让下一步聚焦于你的应用真正需要的那一类 CAPTCHA 操作。一个可见的工具条目为你提供了已验证的起点；它不能代替一次带有正确输入、凭证、浏览器状态和最终应用断言的测试。

在那一步中，使用 CapSolver 专门执行求解操作，并保持 Goose 的角色清晰：发现工具、发起被允许的操作并检查结果。等你准备好在自己拥有或有权操作的工作流上做独立求解测试时，再通过 CapSolver 控制面板准备好账号。

常见问题解答

问：如果这个服务器不在 Goose 的扩展目录里，我还能添加吗？

可以。Goose 支持自定义 MCP 扩展。本地 stdio 配置会将 Goose 指向已安装的官方 Python 服务器。

问：发现检查是否一定需要 CapSolver 密钥？

不需要。示例在密钥为空的情况下加载 supported-types 工具。付费 CAPTCHA 操作需要有效账号密钥以及各自所需的任务输入。

问：为什么 Goose 会在工具名里显示双下划线？

Goose 会在远程工具名前加上扩展名。在这个配置中，capsolver 和 get_supported_captchas 组合起来就成了 capsolver__get_supported_captchas。

问：为什么看不到求解工具？

示例有意只选择了 get_supported_captchas。当你准备好测试这些操作时，请将 available_tools 更新为所需的已文档化工具名称。

问：这个扩展会接管我现有的浏览器标签页吗？

不会。这一配置不会建立任何自动接管。请在将其与其他浏览器扩展或应用组合使用之前，先检查所选工具的输入与浏览器会话行为。

问：看到工具就能证明 CAPTCHA 求解真的可用吗？

不能。它只验证了客户端与服务器之间的连接及工具发现过程。付费求解以及应用端结果需要使用有效凭证与正确工作流输入进行单独测试。