Como configurar ferramentas de resolução de CAPTCHA no Gemini CLI com MCP

Resumo

• O Gemini CLI pode se conectar a um resolvedor de CAPTCHA local por meio da configuração mcpServers.
• Aponte o cliente para o executável do ambiente Python para evitar problemas de PATH.
• Comece pela descoberta de ferramentas antes de habilitar uma resolução paga em um fluxo de trabalho aprovado.
• Um serviço MCP conectado não prova que uma conta consegue resolver um desafio ou que um formulário no navegador foi concluído.
• A confiança em pastas e a aprovação de ferramentas são controles separados; mantenha as confirmações de ferramenta ativadas.

A configuração do resolvedor de CAPTCHA do Gemini CLI começa com a conexão de uma ferramenta. Se o agente no terminal ajuda a manter testes de navegador ou outro fluxo de trabalho web permitido, o resolvedor deve ficar no ponto específico de verificação de CAPTCHA. Ele não deve substituir a navegação normal de páginas, a validação da aplicação ou sua decisão sobre quais operações o agente pode executar.

O CapSolver expõe um serviço MCP local que o Gemini CLI pode descobrir. Este guia conecta os dois usando suas interfaces documentadas, explica como verificar a conexão e mostra onde uma ferramenta de resolução se encaixa depois disso. A configuração executável tem como alvo macOS e Linux. Não é necessário um site de destino para estabelecer a conexão, nem se assume que o Gemini CLI já controle um navegador.

O que um resolvedor de CAPTCHA adiciona ao Gemini CLI?

Um resolvedor de CAPTCHA fornece ao Gemini CLI uma capacidade invocável para um desafio que o fluxo de trabalho em volta já identificou e está autorizado a tratar. O Gemini CLI carrega a configuração do servidor e apresenta as ferramentas disponíveis. O processo MCP fornece as definições das ferramentas e executa a operação solicitada.

Para uma equipe de QA testando a própria aplicação, o teste de navegador pode chegar a um widget de CAPTCHA depois de inserir dados de teste. Um resolvedor pode tratar o desafio suportado nesse ponto, enquanto o teste ainda é responsável pelos dados do formulário e pela asserção de que a aplicação aceitou o envio. Instalar apenas um serviço MCP não constrói essas etapas de navegador.

O Google documenta a conexão do cliente em seu guia de configuração de servidor MCP. O CapSolver documenta os correspondentes papéis de serviço MCP e ferramentas. As duas interfaces se encontram em um processo local via stdio, portanto um adaptador de cliente separado é desnecessário para a descoberta inicial.

O que você precisa antes de conectar as ferramentas?

Você precisa de um runtime Node.js suportado, Python, um diretório de projeto isolado e dos pacotes oficiais de cliente e servidor. A configuração foi verificada com Node.js 24.16.0, Python 3.12.14, Gemini CLI 0.65.0 e capsolver-mcp 0.1.3. Essas versões identificam a combinação testada, não uma exigência de permanecer nelas indefinidamente.

As instruções oficiais de instalação do Gemini CLI explicam os pré-requisitos do cliente. Use Python 3.10 ou mais recente e uma versão de Node.js suportada pelo pacote Gemini fixado. Um ambiente separado permite testar a conexão sem substituir uma configuração de agente existente.

Há duas credenciais diferentes a entender. A autenticação do modelo Gemini permite que o CLI gere respostas. Uma chave de API do CapSolver autoriza operações de conta, como uma resolução paga. Nenhuma credencial substitui a outra. A verificação de conexão abaixo não envia um CAPTCHA nem solicita uma resposta de modelo; resoluções futuras e uso conversacional exigem suas respectivas configurações de conta.

Instale o servidor local e o cliente

Instale os pacotes oficiais no diretório onde você testará a conexão. A partir de um novo diretório de trabalho, crie um ambiente Python e instale os pacotes fixados:

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

A instalação do Python traz a dependência principal. Verifique as versões instaladas se você reproduzir este guia mais tarde: uma mudança de dependência pode alterar ferramentas ou saída mesmo quando sua configuração permanece a mesma. Mantenha o ambiente associado ao projeto para que outra sessão de terminal possa localizá‑lo de forma confiável.

O pacote MCP básico é suficiente para essa conexão. Ferramentas orientadas a navegador têm dependências adicionais. Você não precisa dessas ferramentas para estabelecer a conexão inicial. O tutorial oficial de instalação via registry explica o pacote publicado e as rotas de instalação.

Configure o servidor MCP no Gemini CLI

Configure o Gemini CLI para iniciar o interpretador Python dentro do ambiente que você criou. Mescle esta entrada às suas configurações de usuário existentes em ~/.gemini/settings.json; preserve configurações e servidores não relacionados. Substitua o caminho do executável pelo caminho completo para o py/bin/python do seu projeto.

{
  "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
    }
  }
}

O caminho absoluto do interpretador resolve um problema de configuração comum: o shell conhece um ambiente, mas o cliente inicia outro Python. A referência de variável mantém uma chave de conta literal fora do arquivo JSON. Forneça a chave real por meio do seu processo normal de gerenciamento de segredos antes de solicitar uma operação de conta.

Essa configuração inicial expõe a consulta de capacidades e a ferramenta de resolução orientada a token. Ela mantém ferramentas orientadas a navegador fora da lista de permissão, dando tempo para você decidir como a sessão de navegador deve ser gerenciada. O timeout é uma configuração do cliente em milissegundos, não uma promessa sobre o tempo de conclusão do CAPTCHA.

Mantenha a confiança em pastas separada da confiança em servidor

O Gemini CLI pode desativar servidores MCP quando a pasta atual não é confiável. Siga o fluxo de pastas confiáveis do Google para um projeto que você possua e tenha revisado. Confie no escopo pretendido do projeto em vez de alterar pastas não relacionadas.

A configuração trust: false do servidor serve a um propósito diferente: ela mantém o comportamento de confirmação de chamadas de ferramentas. Um diretório de trabalho confiável não significa que todas as chamadas de ferramentas futuras devam ser aprovadas automaticamente. Mantenha essa distinção ao passar de diagnósticos de conexão para um fluxo de trabalho de aplicação real.

Resgate Seu Código de Bônus CapSolver

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

Verifique a conexão antes de solicitar uma resolução

Verifique o serviço configurado com o comando de listagem MCP do Gemini CLI a partir do diretório do projeto:

npx --no-install gemini mcp list

A verificação bem-sucedida exibiu o servidor capsolver usando stdio com status Connected. O comando exibido incluía o caminho do interpretador e -m capsolver_mcp. Seu caminho absoluto será diferente. Um resultado Disabled aponta para uma decisão de configuração ou confiança; uma conexão com falha exige verificar o executável e a inicialização do processo.

Quando a autenticação normal do Gemini estiver configurada, inspecione as ferramentas pela interface MCP do cliente. Uma primeira solicitação útil é pedir os tipos de CAPTCHA suportados sem resolver nada. A ferramenta pretendida é get_supported_captchas; não a substitua por uma solicitação de saldo de conta ou de resolução quando você só precisa de uma verificação de capacidades.

O limite da verificação é preciso: a conexão local do Gemini CLI foi exercitada contra o processo MCP real. Nenhuma conversa com modelo, desafio pago ou conclusão de formulário no navegador é reivindicada por essa verificação. Esses são testes de aceitação separados para o fluxo de trabalho que você escolher construir.

Coloque o resolvedor em um ponto explícito do navegador

Coloque a operação de resolução entre uma detecção de CAPTCHA confirmada e a próxima verificação em nível de aplicação. Para um teste de navegador sob controle do proprietário, a ordem pretendida é: alcançar o formulário de teste, identificar o desafio suportado, solicitar a operação apropriada, aplicar o resultado documentado e verificar a resposta da aplicação.

A ferramenta orientada a token solve_captcha se encaixa em uma aplicação que já conhece os parâmetros necessários do desafio e detém o restante do trabalho no navegador. Leia o esquema real de entrada antes de solicitar uma chamada. Um desafio antigo ou uma URL de um ambiente diferente não se tornam válidos porque o cliente está conectado.

O CapSolver também documenta detect_captchas e solve_on_page como ferramentas baseadas em navegador. Elas exigem o extra de navegador e Chromium, e o comportamento de sessão deve se adequar à sua aplicação. Não se deve assumir que uma ferramenta baseada em URL compartilha cookies ou a página ativa de um navegador não relacionado controlado por outro agente. Se você precisar operar em uma página já controlada pelo seu programa, revise as interfaces orientadas a página do SDK principal antes de escolher outra rota de integração.

Para uma primeira implantação, escolha um fluxo de trabalho de teste aprovado e registre o seu sinal de conclusão. Um teste de formulário pode exigir um estado de confirmação esperado após o envio de dados de teste conhecidos. Um token retornado é evidência sobre a operação do resolvedor; o estado de confirmação é evidência sobre a aplicação. Mantenha ambos nos resultados de teste sem registrar credenciais ou tokens completos.

Solucione problemas de configuração sem repetir chamadas pagas

Solucione a etapa com falha antes de iniciar outro desafio. Repetir uma resolução paga é desnecessário quando o problema real é um caminho Python ou um serviço MCP desativado.

• Se o processo não puder iniciar, confirme que o interpretador configurado existe e contém o pacote.
• Se o Gemini listar o serviço como desativado, verifique a confiança da pasta e se o servidor foi desativado explicitamente.
• Se o serviço conectar, mas uma ferramenta estiver ausente, compare a lista de permissão e quaisquer exclusões com o nome exato anunciado.
• Se uma operação de conta falhar, verifique a chave e os requisitos de conta sem tratar a descoberta como prova de autenticação.
• Se um resultado chegar mas o formulário não for concluído, inspecione o tratamento do resultado e a validação da aplicação antes de alterar o transporte MCP.

Faça uma mudança por vez e repita a verificação de menor custo que possa confirmá‑la. Após uma atualização, redescubra os nomes e esquemas das ferramentas antes de reutilizar um prompt antigo. Um pequeno registro de configuração contendo versões de pacotes, o nome do servidor e o escopo das ferramentas costuma ser mais útil que um grande log de solicitações não redigidas.

Passe de ferramentas conectadas para um fluxo de trabalho testado

Passe para resoluções reais depois que a conexão local e a transferência pretendida para o navegador estiverem claras. Comece com o escopo de ferramenta mais estreito para a tarefa aprovada e, em seguida, verifique o estado final da aplicação de forma independente. O CapSolver pode fornecer a operação de CAPTCHA enquanto o Gemini CLI ajuda a coordenar o trabalho ao redor.

Use seu painel CapSolver para preparar a conta para esse teste de resolução separado. Mantenha a verificação de conexão como um diagnóstico rápido após mudanças no cliente ou em pacotes.

Perguntas frequentes

P: O Gemini CLI passa a resolver CAPTCHAs sozinho após essa configuração?

Não. A configuração conecta um provedor externo de ferramentas MCP. O fluxo de trabalho ao redor ainda precisa de entradas válidas, uma operação aprovada e uma verificação de resultado da aplicação.

P: Preciso de uma chave de API CapSolver para ver Connected?

A conexão local testada foi bem-sucedida sem uma operação de conta. Uma resolução paga precisa de uma chave válida e dos requisitos de conta aplicáveis; Connected não valida nenhum dos dois.

P: Por que meu servidor MCP está desativado em uma pasta desconhecida?

A política de confiança de pastas do Gemini CLI pode suprimir servidores MCP em um diretório não confiável. Revise a pasta e siga o fluxo de confiança do cliente para o escopo pretendido.

P: Por que a configuração expõe apenas duas ferramentas?

O exemplo permite a consulta de capacidades e a ferramenta de resolução baseada em token. Revise a lista somente depois de analisar outras ferramentas, suas dependências e sua adequação ao fluxo de trabalho.

P: Uma ferramenta de resolução em página reutiliza minha aba de navegador existente?

Não presuma que sim. Verifique o modelo de sessão documentado; uma operação baseada em URL e um objeto de página pertencente ao seu programa de navegador são interfaces diferentes.

P: O que devo testar depois que a conexão MCP funcionar?

Teste um fluxo de trabalho fim a fim autorizado com credenciais válidas e um resultado observável da aplicação. Registre o status do resolvedor separadamente do resultado final da página.