CaptchaNo MCP

Permite que agentes de IA resolvam reCAPTCHA v2/v3/Enterprise, Cloudflare Turnstile, DataDome e captchas de imagem através da API CaptchaNo, com polling automático e um limite de gastos por sessão. Código aberto (MIT), executa com npx -y captchano-mcp.

GitHub

Documentação

Servidor MCP CaptchaNo

O servidor oficial do Model Context Protocol para CaptchaNo. Ele permite que agentes de IA (Claude, Cursor, VS Code Copilot e qualquer outro cliente MCP) resolvam reCAPTCHA v2 / v3 / Enterprise, Cloudflare Turnstile, DataDome e captchas de imagem enquanto executam automação de navegador ou HTTP.

As resoluções são executadas na própria infraestrutura de resolução da CaptchaNo e são cobradas no seu saldo CaptchaNo. Resoluções com falha nunca são cobradas.

Use apenas para automação autorizada. Resolva captchas somente em sites que você possui, sites em que você tem permissão para automatizar ou sites cujos termos permitem (QA dos seus próprios formulários, acessibilidade, monitoramento das suas próprias propriedades, pesquisa com permissão). Você é responsável pelo uso que faz dela.

Site: https://captchano.com
Documentação da API: https://captchano.com/captcha-solver-api
Guia do agente: https://captchano.com/agents/mcp
Suporte: support@captchano.com

Início rápido

Crie uma chave de API em https://captchano.com/dashboard.. As chaves começam com cn-.
Adicione o servidor ao seu cliente MCP (trechos abaixo). Ele roda com npx -y captchano-mcp. Node.js 20.3 ou mais recente é necessário.
Peça ao seu agente algo como "Abra a página de cadastro, resolva o captcha e envie o formulário."

Claude Code

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

Adicione --scope user para disponibilizá-lo em todos os projetos.

Claude Desktop

Edite claude_desktop_config.json (Configurações → Desenvolvedor → Editar Config):

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

Cursor

~/.cursor/mcp.json (global) ou .cursor/mcp.json (projeto):

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

VS Code (modo agente do GitHub Copilot)

.vscode/mcp.json. O VS Code solicita a chave na primeira vez e a armazena com segurança:

{
  "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 e outros clientes

Use o mesmo command / args / env acima: comando 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

Configuração

Toda a configuração é lida de variáveis de ambiente. A chave de API nunca é aceita como argumento de ferramenta.

Variável	Obrigatória	Padrão	Descrição
`CAPTCHANO_API_KEY`	sim	–	Sua chave de API (`cn-...`).
`CAPTCHANO_MAX_SPEND_USD`	não	ilimitado	Teto de gastos para este processo do servidor, em USD. Veja Orçamento.
`CAPTCHANO_WAIT`	não	`45`	Segundos que a API bloqueia em cada solicitação de resolução (`?wait=N`, máx. 120) antes que o servidor alterne para polling.
`CAPTCHANO_TOOL_TIMEOUT`	não	`50`	Máx. de segundos que uma chamada `solve_captcha` leva antes de retornar um resultado `solving` retomável. Muitos clientes MCP cancelam chamadas de ferramenta em 60 s; aumente apenas se o seu permitir mais.
`CAPTCHANO_API_BASE`	não	`https://api.captchano.com`	URL base da API.
`CAPTCHANO_MCP_HTTP_TOKEN`	não	–	No modo `--http`, exige `Authorization: Bearer <token>` em `/mcp`.
`CAPTCHANO_LOG_LEVEL`	não	`info`	`debug`, `info`, `warn`, `error` ou `silent`. Os logs vão apenas para stderr.

Ferramentas

`solve_captcha`

Resolve um captcha e retorna o valor que a página precisa. Cobrado por resolução bem-sucedida.

Argumento	Tipos	Observações
`type`	todos	`recaptcha_v2`, `recaptcha_v3`, `recaptcha_enterprise`, `turnstile`, `datadome`, `image`
`url`	todos exceto `image`	URL completa da página que exibe o captcha
`sitekey`	recaptcha_*, turnstile	De `data-sitekey`, o parâmetro do iframe `k=` ou o parâmetro do script `render=`
`action`	recaptcha_v3, recaptcha_enterprise, turnstile	O nome da ação que a página usa
`minScore`	recaptcha_v3	0,1–0,9
`invisible`	recaptcha_v2, recaptcha_enterprise	`true` para widgets invisíveis
`cData`, `pageData`	turnstile	`data-cdata`; `pageData` para páginas de desafio do Cloudflare
`challengeUrl`	datadome (obrigatório)	URL completa do captcha da resposta bloqueada
`proxy`	datadome (obrigatório), opcional para tipos de token	`"http://user:pass@host:port"` (http, socks4, socks5) ou `{ scheme, host, port, username, password }`
`body`	imagem (obrigatório)	Imagem em Base64. Um prefixo `data:image/...;base64,` é aceito
`userAgent`	todos exceto imagem	O User-Agent do cliente que usará a solução

Como uma chamada funciona: o servidor envia POST /v1/solve?wait=N. Se a API responder 202 (ainda resolvendo), o servidor faz polling em GET /v1/task/{id} a cada 5 segundos, por até 50 segundos no total por padrão (CAPTCHANO_TOOL_TIMEOUT). Se a tarefa ainda estiver resolvendo após isso, o resultado terá status: "solving" e o id da tarefa, e o agente deve chamar get_task com esse id em vez de resolver novamente.

O resultado retorna como texto (token, cookie ou texto, userAgent, custo, tempo de resolução e o próximo passo) e como structuredContent:

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

`get_task`

{ id } → o mesmo objeto. Use para retomar uma resolução que ainda está solving, ou para ler um resultado novamente. As soluções são mantidas por 10 minutos. Somente leitura e gratuito.

`get_balance`

Retorna { balance, currency, sessionSpend }. Somente leitura e gratuito.

`list_captcha_types`

Uma lista estática de todos os tipos suportados: seus campos obrigatórios e opcionais, qual campo de solução retorna e uma dica de uma linha sobre onde encontrar o sitekey (ou outras entradas) na página. Não faz nenhuma chamada de rede.

Erros

Erros da API retornam como resultados de ferramenta com isError: true. Cada um inclui o código de erro, a mensagem da API e uma dica do que fazer em seguida. Por exemplo:

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.

Códigos da 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. Códigos deste servidor: invalid_arguments (capturado antes de qualquer solicitação ser enviada), budget_exhausted, network_error, timeout, cancelled, http_error.

Orçamento

Defina CAPTCHANO_MAX_SPEND_USD para limitar o que um processo do servidor pode gastar. O servidor soma os cost que a API retorna para cada tarefa enviada, contando cada tarefa uma vez. Quando o total atinge o limite, solve_captcha retorna budget_exhausted sem contatar a API. get_task, get_balance e list_captcha_types continuam funcionando.

Observações:

O limite se aplica a cada processo. Reiniciar o servidor ou o cliente MCP o redefine. Para um limite rígido em toda a conta, mantenha apenas um saldo pequeno na chave.
O limite é verificado antes de cada resolução. Uma resolução que começa logo abaixo do limite pode terminar ligeiramente acima dele, no máximo pelo custo das resoluções já em andamento.

Modo 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

Streamable HTTP sem estado em /mcp, além de GET /healthz.
Vincula-se a 127.0.0.1 por padrão. Use --host 0.0.0.0 apenas atrás de TLS e com CAPTCHANO_MCP_HTTP_TOKEN definido: qualquer pessoa que possa alcançar o endpoint pode gastar seu saldo.
A chave sempre vem do ambiente do servidor, nunca dos chamadores.

Segurança

Chaves: CAPTCHANO_API_KEY é lida apenas do ambiente. Nunca é um argumento de ferramenta, nunca incluída em resultados de ferramenta e nunca registrada em logs. As linhas de log também são limpas de qualquer coisa que pareça uma chave cn-, um token bearer ou credenciais de proxy.
stdout é o canal do protocolo. Todo o registro vai para stderr.
Gastos: toda solve_captcha bem-sucedida é cobrada. Use CAPTCHANO_MAX_SPEND_USD e uma chave dedicada com saldo pequeno para agentes autônomos. A ferramenta é anotada como uma ferramenta não somente leitura e de mundo aberto, então clientes que pedem confirmação perguntarão antes de executá-la.
Proxies: as credenciais de proxy são enviadas apenas para a API CaptchaNo, via HTTPS, e nunca são repetidas em resultados ou logs.
Injeção de prompt: uma página que um agente visita pode tentar fazê-lo resolver captchas em outros sites. Mantenha um humano no loop para chamadas de resolução que você não esperava e use o limite de gastos.
Relate vulnerabilidades para support@captchano.com.

Desenvolvimento

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 chama get_balance contra a API real com uma chave fictícia e espera um resultado invalid_api_key limpo. Se CAPTCHANO_TEST_API_KEY estiver definido, também executa uma resolução ao vivo do demo público de reCAPTCHA v2, com um limite de US$ 0,05.