Solvedor de CAPTCHA da Claude Code: Guia de Configuração do CapSolver MCP

TL;DR

• Conecte o Claude Code ao pacote oficial capsolver-mcp para expor as ferramentas de resolução de CAPTCHA compatíveis.
• Comece listando os tipos de CAPTCHA compatíveis; uma conexão bem-sucedida de ferramenta não prova que uma solicitação de resolução paga terá sucesso.
• Use solve_captcha quando você já tiver o tipo de desafio compatível, a URL da página e o sitekey.
• As ferramentas de página abrem sua própria sessão do navegador; elas não continuam automaticamente uma aba do navegador do Claude existente.
• Um token retornado ou um widget preenchido ainda precisa da verificação final da aplicação-alvo.

O Claude Code pode ajudar a escrever ou depurar uma tarefa de navegador, mas ele precisa de uma ferramenta real de resolução quando uma CAPTCHA compatível interromper a operação aprovada. Pedir ao modelo para "tentar mais" não fornece os parâmetros do site, a conexão da API ou o tratamento dos resultados que o desafio exige.

CapSolver expõe essas capacidades por meio de seu serviço MCP. Este guia aborda a instalação do pacote, a conexão com o Claude Code, a verificação das ferramentas disponíveis e a escolha da chamada de resolução. Os exemplos envolvem suas próprias páginas ou tarefas de automação permitidas. Eles não automatizam a criação de contas, compras ou acesso a dados restritos.

O que o Claude Code pode fazer com o CapSolver MCP?

O Claude Code pode descobrir e chamar as ferramentas do CapSolver MCP após você configurar e aprovar o servidor.

O serviço MCP oficial expõe cinco ferramentas:

Os nomes das ferramentas descrevem operações separadas. Uma consulta de saldo não reconhece uma página, e detectar um widget não o resolve. Comece com a operação que você realmente precisa.

A versão instalada verificada neste guia, capsolver-mcp 0.1.3, listou reCaptchaV2, reCaptchaV3 e cloudflare por meio de sua ferramenta de tipo compatível. Nessa interface, o manipulador do Cloudflare se refere ao Turnstile. Não interprete o nome como suporte universal para toda resposta do Cloudflare ou desafio de página completa.

A API REST oferece outros tipos de tarefa, mas esses não são automaticamente adicionados a esse conjunto de ferramentas MCP. Em particular, não passe uma tarefa ImageToText para solve_captcha apenas porque a API separada do CapSolver suporta reconhecimento de imagem.

Instale os Pacotes Oficiais

Instale o núcleo do CapSolver, o servidor MCP e as dependências do navegador no ambiente Python que o Claude Code iniciará.

Os seguintes comandos fixam as versões do núcleo e do MCP usadas aqui:

python -m pip install capsolver-core==0.1.1 "capsolver-mcp[browser]==0.1.3"
python -m playwright install chromium

A instalação segue as instruções oficiais do pacote do CapSolver. O extra do navegador e o Chromium são necessários para as ferramentas de página. O guia de instalação do navegador Playwright explica que os binários do navegador são uma dependência separada do pacote Python.

Use o executável do Python deste ambiente na próxima etapa. Se você instalar em um ambiente virtual e configurar um Python diferente, o cliente pode relatar que não consegue importar capsolver_mcp, mesmo que a instalação tenha sido bem-sucedida em outro local.

Você também precisa do Claude Code e de uma chave de conta do CapSolver para resolução real. Armazene essa chave como CAPSOLVER_API_KEY na variável de ambiente usada para iniciar o Claude Code. Não cole-a em uma mensagem de chat ou comite-a em um arquivo de projeto compartilhado.

A conexão do pacote e o caminho de detecção local podem ser verificados separadamente da reconhecimento pago. Este guia não demonstra uma resolução paga em tempo real; esse passo requer sua conta e os parâmetros atuais de um alvo aprovado.

Adicione o CapSolver à Configuração do Projeto MCP

Adicione uma entrada capsolver ao .mcp.json do projeto, apontando para o ambiente Python onde você instalou os pacotes.

A configuração abaixo usa o padrão documentado do módulo Python do CapSolver e a expansão de variáveis de ambiente do Claude Code. Substitua o caminho do Python pelo caminho absoluto real para o seu ambiente:

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

Se .mcp.json já contiver outros servidores, adicione esta entrada dentro do objeto mcpServers existente, em vez de substituir o arquivo. A chave permanece fora do arquivo JSON, mas a variável ainda precisa estar disponível quando o Claude Code for iniciado.

A documentação de configuração MCP do Claude Code aborda o escopo do projeto, a expansão de variáveis de ambiente e a aprovação do servidor. Inicie o Claude Code a partir do projeto desejado, revise o prompt de aprovação do servidor do projeto e aprova esse servidor apenas após confirmar o comando e o pacote que você instalou.

Verifique a configuração a partir do diretório do projeto:

claude mcp list

Dentro de uma sessão interativa do Claude Code, use /mcp para inspecionar o status do servidor e os controles disponíveis. Um status de aprovação pendente significa que o servidor do projeto ainda precisa da sua revisão. É diferente de um executável ausente ou conexão falhada.

Verifique as Ferramentas Antes de Solicitar uma Resolução

Peça ao Claude Code para listar os tipos de CAPTCHA compatíveis antes de pedir que ele gaste créditos da conta.

Uma solicitação adequada é:

Use a ferramenta CapSolver get_supported_captchas e me diga quais tipos de CAPTCHA esse servidor suporta atualmente. Não envie uma tarefa de resolução.

Isso confirma que o cliente pode alcançar uma ferramenta real e fornece a cobertura real do servidor instalado. A vida útil da conexão do MCP separa a inicialização das operações posteriores; estabelecer a conexão é apenas o começo de uma integração utilizável.

Para uma verificação de conta, você pode então pedir get_balance. Mantenha a resposta privada se ela contiver informações da conta. Uma falha aqui aponta para acesso à conta ou comunicação de serviço e deve ser resolvida antes de tentar uma resolução paga.

Não julgue a prontidão a partir da afirmação de um modelo de que ele "sabe do CapSolver." Inspeccione o resultado real da ferramenta. Uma ferramenta descoberta, uma consulta de conta bem-sucedida e uma resolução de CAPTCHA concluída estabelecem fatos diferentes.

Resgate seu código promocional do CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código promocional CAP26 ao recarregar sua conta do CapSolver para obter um bônus adicional de 5% em cada recarga — sem limites.
Resgate-o agora em seu Painel do CapSolver

Use o modo de token para parâmetros de desafio conhecidos

Use solve_captcha quando o fluxo aprovado do navegador ou aplicativo já forneça os parâmetros necessários do tipo, URL da página e sitekey.

Por exemplo, forneça ao Claude Code uma instrução limitada, como:

Use a ferramenta solve_captcha do CapSolver uma vez para o reCAPTCHA v2 na minha página de teste aprovada. Use a URL da página e o sitekey exatos que eu fornece. Se algum deles estiver ausente, informe que a entrada está faltando em vez de adivinhar. Retorne o status da ferramenta sem imprimir o token completo no seu resumo.

O esquema da ferramenta usa captcha_type, website_url e website_key. Verifique o esquema descoberto para parâmetros adicionais necessários pelo desafio que você está lidando. Não copie nomes de tarefas da REST para o campo de tipo MCP: reCaptchaV2 é o valor MCP, enquanto a API REST tem seus próprios nomes de tarefas documentados.

Seu aplicativo então precisa consumir o token retornado através do fluxo pretendido da aplicação-alvo. A chamada MCP em si não submete todos os formulários ou verifica um resultado comercial. Para entradas de reCAPTCHA específicas da página, consulte a documentação da tarefa reCAPTCHA v2.

Se um parâmetro for desconhecido, inspecione a página aprovada atual com as ferramentas apropriadas do navegador. Um sitekey lembrado de outra página não é evidência para o widget atual. Mantenha a resolução conectada à operação real que está sendo depurada.

Use as ferramentas de página com a fronteira do navegador em mente

As ferramentas de página aceitam uma URL e operam em uma sessão do navegador criada pelo serviço MCP.

Para detecção, uma solicitação útil é:

Chame a ferramenta detect_captchas do CapSolver nesta URL de página aprovada e relate o tipo detectado. Não resolva-o ainda.

Quando resolver essa página for a operação pretendida, solve_on_page pode executar sua sequência documentada de detecção, resolução e preenchimento. Revise o desafio observado e a cobertura compatível antes de solicitar essa chamada.

A fronteira importante é visível no implementação oficial do MCP: essas ferramentas abrem um navegador para a chamada e o fecham após. Elas não se conectam a uma aba mantida por outro navegador MCP ou herdaram automaticamente seu estado de login.

Isso torna uma página de teste direta e acessível um ponto de partida mais claro do que uma página disponível apenas após vários passos de sessão privada. Se sua tarefa precisar permanecer em uma página do navegador que você já controla, use uma integração compatível que opere nessa página existente. O SDK Core do CapSolver documenta as capacidades do adaptador de navegador para essa necessidade de integração diferente.

O guia Uso do Computador do Claude discute uma superfície adjacente de agente de navegador. O Uso do Computador do Claude e esta configuração do Claude Code MCP não devem ser tratados como configurações intercambiáveis.

Corrija erros de configuração antes de repetir chamadas de CAPTCHA

A maioria dos erros de configuração pode ser reduzida ao caminho do executável, ambiente, instalação do navegador ou entrada da tarefa.

Se o comando do servidor não for encontrado, use o caminho absoluto do Python mostrado acima. Se o pacote não puder ser importado, verifique se o mesmo ambiente Python contém capsolver-mcp e capsolver-core.

Se a detecção de página relatar um executável de navegador ausente, execute o comando de instalação do Chromium no ambiente que inicia o servidor MCP. O modo de token não requer um navegador apenas para chamar o serviço de resolução, então distinga uma falha no início do navegador de uma falha na API do solucionador.

Se o servidor se conectar, mas uma chamada de API falhar, mantenha o código de erro retornado e um resumo redigido. Verifique a chave da conta, o tipo compatível, os inputs necessários e o estado da página atual antes de outra tentativa.

Se uma resolução retornar um token, mas a aplicação original permanecer inalterada, inspecione o consumo do resultado. Confirme que o resultado foi usado pelo fluxo pretendido e que você não assumiu que duas sessões de navegador separadas compartilhavam estado.

Mantenha um limite pequeno em tentativas repetidas. Quando o mesmo erro permanecer não resolvido, retorne a evidência para revisão em vez de instruir o agente a repetir indefinidamente.

Construa fluxos de automação confiáveis com o CapSolver

Comece com uma conexão MCP real, inspecione o conjunto de ferramentas instalado e solicite a operação que corresponda ao desafio na sua tarefa aprovada.

CapSolver fornece ao Claude Code uma capacidade documentada de resolução de CAPTCHA. Entradas corretas e uma fronteira de navegador clara tornam essa capacidade útil; a resposta da aplicação final lhe diz se a tarefa pretendida realmente foi concluída.

Perguntas Frequentes

Q: Eu preciso de dependências de navegador para cada ferramenta MCP?

Não. As ferramentas de página precisam do extra do navegador e do Chromium. As soluções de token e as consultas de conta ou cobertura não precisam abrir um navegador apenas para chamar seus serviços correspondentes ou capacidades locais.

Q: O CapSolver MCP pode continuar minha aba de navegador existente?

As ferramentas de página na versão verificada abrem e fecham sua própria sessão de navegador. Não suponha que elas controlem uma aba pertencente a outra ferramenta de navegador.

Q: O servidor MCP suporta todas as tarefas REST do CapSolver?

Não. Verifique get_supported_captchas e o esquema da ferramenta descoberta. Capacidades REST separadas não são automaticamente expostas por meio deste pacote MCP.

Q: Por que o Claude Code mostra aprovação pendente?

Um servidor MCP de projeto pode exigir aprovação antes de ser usado. Revise-o no Claude Code e confirme o comando configurado em vez de tratar o status de aprovação como um erro de chave de API.

Q: Uma resolução bem-sucedida significa que o agente terminou sua tarefa?

Não. Verifique se o resultado foi consumido pela aplicação pretendida e se a operação da página solicitada foi concluída. Um token ou widget preenchido é um resultado intermediário.