CaptchaNo

CaptchaNo MCP 服务

CaptchaNo 的官方 Model Context Protocol 服务。 它让 AI Agent（Claude、Cursor、VS Code Copilot 以及其他任何 MCP 客户端）在运行浏览器或 HTTP 自动化时，解决 reCAPTCHA v2 / v3 / Enterprise、Cloudflare Turnstile、DataDome 和图片 验证码。

验证码由 CaptchaNo 自有的解题基础设施处理，费用从您的 CaptchaNo 余额中扣除。 解题失败绝不会收费。

仅将其用于获得授权的自动化。 仅在您拥有的网站、您获准进行自动化操作的网站，或其条款允许的网站上解决验证码（例如对自有表单进行 QA、无障碍访问、监控自有网站、经授权开展研究）。您须对自己的使用方式负责。

• 网站：https://captchano.com
• API 文档：https://captchano.com/captcha-solver-api
• Agent 指南：https://captchano.com/agents/mcp
• 支持：[email protected]

快速开始

1. 在 https://captchano.com/dashboard 创建 API 密钥。密钥以 cn- 开头。
2. 将服务添加到您的 MCP 客户端（配置示例如下）。运行命令为 npx -y captchano-mcp。 需要 Node.js 20.3 或更高版本。
3. 向您的 Agent 提出类似这样的请求：“打开注册页面，解决验证码并提交表单。”

Claude Code

claude mcp add captchano -e CAPTCHANO_API_KEY=cn-... -- npx -y captchano-mcp

添加 --scope user，即可在所有项目中使用。

Claude Desktop

编辑 claude_desktop_config.json（设置 → 开发者 → 编辑配置）：

{
  "mcpServers": {
    "captchano": {
      "command": "npx",
      "args": ["-y", "captchano-mcp"],
      "env": {
        "CAPTCHANO_API_KEY": "cn-...",
        "CAPTCHANO_MAX_SPEND_USD": "1.00"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

{
  "mcpServers": {
    "captchano": {
      "command": "npx",
      "args": ["-y", "captchano-mcp"],
      "env": { "CAPTCHANO_API_KEY": "cn-..." }
    }
  }
}

VS Code（GitHub Copilot Agent 模式）

.vscode/mcp.json。VS Code 会在首次使用时询问密钥，并安全地保存该密钥：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "captchano-api-key",
      "description": "CaptchaNo API key (cn-...)",
      "password": true
    }
  ],
  "servers": {
    "captchano": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "captchano-mcp"],
      "env": { "CAPTCHANO_API_KEY": "${input:captchano-api-key}" }
    }
  }
}

Windsurf、Cline、Zed 和其他客户端

使用与上述相同的 command / args / env：命令为 npx，args 为 ["-y", "captchano-mcp"]， env 为 CAPTCHANO_API_KEY。

Docker

docker build -t captchano-mcp .
docker run -i --rm -e CAPTCHANO_API_KEY=cn-... captchano-mcp

配置

所有配置均通过环境变量读取。API 密钥绝不会作为工具参数传入。

变量	必填	默认值	描述
CAPTCHANO_API_KEY	是	–	您的 API 密钥（cn-...）。
CAPTCHANO_MAX_SPEND_USD	否	不限	此服务进程的 USD 支出上限。参见预算。
CAPTCHANO_WAIT	否	45	API 在每次解题请求时阻塞的秒数（?wait=N，最多 120 秒），超时后服务将切换为轮询。
CAPTCHANO_TOOL_TIMEOUT	否	50	一次 solve_captcha 调用返回可恢复的 solving 结果前的最长耗时（秒）。许多 MCP 客户端会在 60 秒时取消工具调用；只有在客户端允许更长时间时才调高此值。
CAPTCHANO_API_BASE	否	https://api.captchano.com	API 基础 URL。
CAPTCHANO_MCP_HTTP_TOKEN	否	–	在 --http 模式下，要求访问 /mcp 时提供 Authorization: Bearer <token>。
CAPTCHANO_LOG_LEVEL	否	info	debug、info、warn、error 或 silent。日志仅写入 stderr。

工具

solve_captcha

解决验证码并返回页面所需的值。每次成功解决都会计费。

参数	类型	说明
type	所有类型	recaptcha_v2、recaptcha_v3、recaptcha_enterprise、turnstile、datadome、image
url	除 image 外的所有类型	显示验证码的页面完整 URL
sitekey	recaptcha_*、turnstile	来自 data-sitekey、k= iframe 参数或 render= 脚本参数
action	recaptcha_v3、recaptcha_enterprise、turnstile	页面使用的操作名称
minScore	recaptcha_v3	0.1–0.9
invisible	recaptcha_v2、recaptcha_enterprise	对于不可见组件，设为 true
cData、pageData	turnstile	data-cdata；对于 Cloudflare 挑战页面，使用 pageData
challengeUrl	datadome（必填）	被拦截响应中的验证码完整 URL
proxy	datadome（必填），令牌类型可选	"http://user:pass@host:port"（http、socks4、socks5）或 { scheme, host, port, username, password }
body	image（必填）	Base64 图像。接受带有 data:image/...;base64, 前缀的内容
userAgent	除 image 外的所有类型	将使用解决方案的客户端的 User-Agent

调用的运行方式：服务端发送 POST /v1/solve?wait=N。如果 API 返回 202（仍在解决中），服务端会每隔 5 秒轮询一次 GET /v1/task/{id}，默认总计最多等待 50 秒（CAPTCHANO_TOOL_TIMEOUT）。 如果任务在此之后仍在解决，结果会包含 status: "solving" 和任务 ID；Agent 应使用该 ID 调用 get_task，而不是再次解决。

结果会以文本形式返回（令牌、Cookie 或文本、userAgent、cost、solveTime 和下一步操作）， 也会以 structuredContent 返回：

{
  "id": "…",
  "type": "recaptcha_v2",
  "status": "ready",
  "token": "03AFcWeA…",
  "cost": "…",
  "solveTime": "…",
  "sessionSpend": { "spentUsd": "…", "limitUsd": "1.0000", "remainingUsd": "…" }
}

get_task

{ id } → 相同对象。用于继续仍处于 solving 状态的解决任务，或再次读取结果。解决结果会保留 10 分钟。只读且免费。

get_balance

返回 { balance, currency, sessionSpend }。只读且免费。

list_captcha_types

静态列出所有受支持的类型：其必填和可选字段、返回的解决方案字段，以及一行关于如何在页面上找到 sitekey（或其他输入项）的提示。不进行网络调用。

错误

API 错误会作为工具结果返回，并带有 isError: true。每个错误都包含错误代码、API 的消息以及后续操作提示。例如：

Error insufficient_balance: Insufficient balance
Hint: The CaptchaNo account has no balance left. Ask the user to top up at https://captchano.com/dashboard/topup, then retry. Failed solves are never billed.

API 代码：invalid_api_key、insufficient_balance、unsupported_type、invalid_sitekey、proxy_required、proxy_unreachable、score_not_met、unsolvable、capacity_unavailable、rate_limited、task_not_found、upstream_error。 此服务的错误代码：invalid_arguments（发送任何请求前捕获）、budget_exhausted、network_error、timeout、cancelled、http_error。

预算

设置 CAPTCHANO_MAX_SPEND_USD，以限制单个服务端进程的支出。服务端会累计 API 对其提交的每个任务返回的 cost，每个任务只计一次。累计金额达到上限后，solve_captcha 会返回 budget_exhausted，且不会联系 API。get_task、get_balance 和 list_captcha_types 仍可正常使用。

注意：

• 上限适用于每个进程。重启服务端或 MCP 客户端会重置上限。若要设置账户级硬性上限，请确保密钥中只保留少量余额。
• 每次解决前都会检查上限。开始时略低于上限的解决任务，完成后可能会略微超出上限，但超出金额最多为已在进行的解决任务的费用。

HTTP 模式

CAPTCHANO_API_KEY=cn-... CAPTCHANO_MCP_HTTP_TOKEN=$(openssl rand -hex 24) \
  npx -y captchano-mcp --http --port 8080            # serves http://127.0.0.1:8080/mcp

• 在 /mcp 提供无状态 Streamable HTTP，并提供 GET /healthz。
• 默认绑定到 127.0.0.1。仅在 TLS 后方且已设置 CAPTCHANO_MCP_HTTP_TOKEN 时使用 --host 0.0.0.0：任何能够访问该端点的人都可以花费你的余额。
• 密钥始终来自服务端环境，绝不会来自调用方。

安全

• **密钥：**仅从环境中读取 CAPTCHANO_API_KEY。它绝不会作为工具参数，也不会包含在工具结果中，更不会被记录到日志中。日志行也会清除所有看起来像 cn- 密钥、Bearer 令牌或代理凭据的内容。
• **stdout 是协议通道。**所有日志都输出到 stderr。
• **支出：**每次成功的 solve_captcha 调用都会产生费用。对于自主 Agent，请使用 CAPTCHANO_MAX_SPEND_USD，并使用余额较少的专用密钥。该工具被标注为非只读、开放世界工具，因此，要求确认的客户端会在运行前询问。
• **代理：**代理凭据仅通过 HTTPS 发送给 CaptchaNo API，不会再次出现在结果或日志中。
• **提示词注入：**Agent 访问的页面可能会试图诱使它为其他网站解决验证码。对于你未预料到的解决请求，请让人工参与，并设置支出上限。
• 请将漏洞报告发送至 [email protected]。

开发

npm install
npm test          # unit tests (node:test, mocked fetch)
npm run e2e       # builds, then drives dist/ over stdio and HTTP with the official MCP client
npm run check     # typecheck + tests + build

npm run e2e 会使用虚拟密钥调用真实 API 上的 get_balance，并要求 API 返回干净的 invalid_api_key 结果。如果设置了 CAPTCHANO_TEST_API_KEY，它还会对公开的 reCAPTCHA v2 演示进行一次实时求解，并将费用上限设为 $0.05。

许可证

MIT © DishIs Technologies LLC