Cómo configurar herramientas de resolución de CAPTCHA en Gemini CLI con MCP

Resumen

• Gemini CLI puede conectarse a un solucionador de CAPTCHA local mediante su configuración mcpServers.
• Apunta el cliente al ejecutable del entorno de Python para evitar problemas con el PATH.
• Empieza con el descubrimiento de herramientas antes de habilitar resoluciones de pago en un flujo de trabajo aprobado.
• Un servicio MCP conectado no demuestra que una cuenta pueda resolver un desafío ni que se haya completado un formulario en el navegador.
• La confianza en carpetas y la aprobación de herramientas son controles distintos; mantén habilitadas las confirmaciones de herramientas.

La configuración del solucionador de CAPTCHA en Gemini CLI comienza con la conexión de una herramienta. Si tu agente de terminal ayuda a mantener pruebas de navegador u otro flujo web permitido, el solucionador debe situarse en el punto concreto de control del CAPTCHA. No debe reemplazar la navegación ordinaria de páginas, la validación de la aplicación ni tu decisión sobre qué operaciones puede realizar el agente.

CapSolver expone un servicio MCP local que Gemini CLI puede descubrir. Esta guía conecta ambos usando sus interfaces documentadas, explica cómo comprobar la conexión y muestra dónde encaja una herramienta de resolución después. La configuración ejecutable está orientada a macOS y Linux. No requiere un sitio web de destino para establecer la conexión y no asume que Gemini CLI ya controle un navegador.

¿Qué añade un solucionador de CAPTCHA a Gemini CLI?

Un solucionador de CAPTCHA proporciona a Gemini CLI una capacidad invocable para un desafío que el flujo de trabajo ya ha identificado y está autorizado a manejar. Gemini CLI carga la configuración del servidor y presenta las herramientas disponibles. El proceso MCP suministra las definiciones de herramientas y realiza la operación solicitada.

Para un equipo de QA que prueba su propia aplicación, la prueba de navegador puede llegar a un widget de CAPTCHA después de introducir datos de prueba. Un solucionador puede gestionar el desafío admitido en ese punto, mientras la prueba sigue controlando los datos del formulario y la afirmación de que la aplicación aceptó el envío. Instalar un servicio MCP por sí solo no construye esos pasos de navegador.

Google documenta la conexión del cliente en su guía de configuración de servidores MCP. CapSolver documenta los correspondientes roles de servicio MCP y herramientas. Ambas interfaces se encuentran en un proceso local por stdio, por lo que no es necesario un adaptador de cliente separado para el descubrimiento inicial.

¿Qué necesitas antes de conectar las herramientas?

Necesitas un runtime de Node.js compatible, Python, un directorio de proyecto aislado y los paquetes oficiales de cliente y servidor. La configuración se comprobó con Node.js 24.16.0, Python 3.12.14, Gemini CLI 0.65.0 y capsolver-mcp 0.1.3. Estas versiones identifican la combinación probada, no un requisito para permanecer en ellas indefinidamente.

Las instrucciones oficiales de instalación de Gemini CLI explican los prerrequisitos del cliente. Usa Python 3.10 o superior y una versión de Node.js admitida por el paquete Gemini fijado. Un entorno separado te permite probar la conexión sin reemplazar una configuración de agente existente.

Hay dos credenciales distintas que debes entender. La autenticación del modelo de Gemini permite que la CLI genere respuestas. Una clave de API de CapSolver autoriza operaciones de cuenta, como una resolución de pago. Ninguna credencial sustituye a la otra. La comprobación de conexión de más abajo no envía un CAPTCHA ni solicita una respuesta de modelo; las resoluciones posteriores y el uso conversacional requieren sus respectivas configuraciones de cuenta.

Instala el servidor local y el cliente

Instala los paquetes oficiales en el directorio donde probarás la conexión. Desde un nuevo directorio de trabajo, crea un entorno de Python e instala los paquetes fijados:

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

La instalación de Python incorpora la dependencia principal. Comprueba las versiones instaladas si reproduces esta guía más adelante: un cambio de dependencia puede alterar herramientas o salida incluso cuando tu configuración permanece igual. Mantén el entorno asociado al proyecto para que otra sesión de terminal pueda localizarlo de forma fiable.

El paquete MCP base es suficiente para esta conexión. Las herramientas orientadas a navegador tienen dependencias adicionales. No necesitas esas herramientas para establecer la conexión inicial. El tutorial oficial de instalación desde el registro explica el paquete publicado y las rutas de instalación.

Configura el servidor MCP en Gemini CLI

Configura Gemini CLI para que inicie el intérprete de Python dentro del entorno que creaste. Fusiona esta entrada con tu configuración de usuario existente en ~/.gemini/settings.json; conserva los ajustes y servidores no relacionados. Sustituye la ruta del ejecutable por la ruta absoluta a py/bin/python de tu proyecto.

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

La ruta absoluta al intérprete resuelve un problema de configuración común: el shell conoce un entorno, pero el cliente inicia un Python diferente. La referencia a la variable mantiene una clave de cuenta literal fuera del archivo JSON. Proporciona la clave real mediante tu proceso normal de gestión de secretos antes de solicitar una operación de cuenta.

Esta configuración inicial expone la consulta de capacidades y la herramienta de resolución orientada a tokens. Deja las herramientas orientadas a navegador fuera de la lista de permitidas, dándote tiempo para decidir cómo debe gestionarse la sesión del navegador. El timeout es un ajuste del cliente en milisegundos, no una promesa sobre el tiempo de resolución del CAPTCHA.

Mantén separada la confianza en carpetas y la confianza en servidores

Gemini CLI puede deshabilitar servidores MCP cuando la carpeta actual no es de confianza. Sigue el flujo de trabajo de carpetas de confianza de Google para un proyecto que poseas y hayas revisado. Otorga confianza al alcance de proyecto previsto en lugar de cambiar carpetas no relacionadas.

El ajuste trust: false del servidor cumple un propósito distinto: mantiene el comportamiento de confirmación de llamadas a herramientas. Un directorio de trabajo de confianza no implica que todas las futuras llamadas a herramientas deban aprobarse automáticamente. Conserva esa distinción cuando pases de diagnósticos de conexión a un flujo de trabajo de aplicación real.

Canjea tu código de bonificación de CapSolver

Aumenta tu presupuesto de automatización al instante.
Usa el código de bonificación CAP26 al recargar tu cuenta de CapSolver para obtener un 5% extra de bonificación en cada recarga, sin límites.
Canjéalo ahora en tu panel de CapSolver

Verifica la conexión antes de solicitar una resolución

Verifica el servicio configurado con el comando de listado MCP de Gemini CLI desde el directorio del proyecto:

npx --no-install gemini mcp list

La comprobación correcta mostró el servidor capsolver usando stdio con estado Connected. El comando mostrado incluía la ruta del intérprete y -m capsolver_mcp. Tu ruta absoluta será distinta. Un resultado Disabled apunta a una decisión de configuración o confianza; una conexión fallida exige comprobar el ejecutable y el inicio del proceso.

Una vez configurada la autenticación normal de Gemini, inspecciona las herramientas mediante la interfaz MCP del cliente. Una primera solicitud útil es pedir los tipos de CAPTCHA admitidos sin resolver nada. La herramienta prevista es get_supported_captchas; no la sustituyas por una petición de saldo de cuenta o de resolución cuando solo necesitas una comprobación de capacidades.

El límite de verificación es preciso: la conexión local de Gemini CLI se ejercitó contra el proceso MCP real. Esa comprobación no afirma que haya una conversación con modelo, un desafío de pago o una finalización de formulario en navegador. Esas son pruebas de aceptación separadas para el flujo de trabajo que elijas construir.

Coloca el solucionador en un punto de control explícito del navegador

Sitúa la operación de resolución entre una detección confirmada de CAPTCHA y la siguiente verificación a nivel de aplicación. Para una prueba de navegador controlada por el propietario, el orden previsto es: llegar al formulario de prueba, identificar el desafío admitido, solicitar la operación adecuada, aplicar el resultado documentado y comprobar la respuesta de la aplicación.

La herramienta orientada a tokens solve_captcha encaja en una aplicación que ya conoce los parámetros necesarios del desafío y controla el resto del trabajo de navegador. Lee su esquema real de entrada antes de solicitar una llamada. Un desafío antiguo o una URL de un entorno diferente no se vuelven válidos porque el cliente esté conectado.

CapSolver también documenta detect_captchas y solve_on_page como herramientas basadas en navegador. Requieren el extra de navegador y Chromium, y su comportamiento de sesión debe adaptarse a tu aplicación. No debes asumir que una herramienta basada en URL comparte las cookies o la página activa de un navegador distinto controlado por otro agente. Si necesitas operar sobre una página que ya posee tu programa, revisa antes las interfaces orientadas a páginas del SDK principal antes de elegir otra ruta de integración.

Para un primer despliegue, elige un único flujo de trabajo de prueba aprobado y anota su señal de finalización. Una prueba de formulario podría requerir un estado de confirmación esperado tras enviar datos de prueba conocidos. Un token devuelto es evidencia sobre la operación del solucionador; el estado de confirmación es evidencia sobre la aplicación. Conserva ambos en tus resultados de prueba sin registrar credenciales ni tokens completos.

Soluciona problemas de configuración sin repetir llamadas de pago

Soluciona la etapa fallida antes de iniciar otro desafío. Repetir una resolución de pago es innecesario cuando el problema real es una ruta de Python o un servicio MCP deshabilitado.

• Si el proceso no puede iniciarse, confirma que el intérprete configurado existe y contiene el paquete.
• Si Gemini muestra el servicio como deshabilitado, comprueba la confianza de la carpeta y si el servidor se desactivó explícitamente.
• Si el servicio se conecta pero falta una herramienta, compara la lista de permitidas y cualquier exclusión con el nombre anunciado exacto.
• Si falla una operación de cuenta, revisa la clave y los requisitos de cuenta sin tratar el descubrimiento como prueba de autenticación.
• Si llega un resultado pero el formulario no se completa, inspecciona el manejo del resultado y la validación de la aplicación antes de cambiar el transporte MCP.

Realiza un cambio cada vez y repite la comprobación de menor coste que pueda confirmarlo. Tras una actualización, vuelve a descubrir los nombres de herramientas y esquemas antes de reutilizar un prompt antiguo. Un pequeño registro de configuración que contenga versiones de paquetes, nombre de servidor y alcance de herramientas suele ser más útil que un gran registro de peticiones sin editar.

Pasa de herramientas conectadas a un flujo de trabajo probado

Pasa a resoluciones reales después de que la conexión local y la entrega prevista al navegador estén claras. Empieza con el alcance de herramientas más reducido para la tarea aprobada y luego verifica el estado final de la aplicación de forma independiente. CapSolver puede proporcionar la operación de CAPTCHA mientras Gemini CLI ayuda a coordinar el trabajo que la rodea.

Usa tu panel de CapSolver para preparar la cuenta para esa prueba de resolución independiente. Conserva la comprobación de conexión como un diagnóstico rápido tras cambios en el cliente o en los paquetes.

Preguntas frecuentes

P: ¿Resuelve Gemini CLI los CAPTCHAs por sí solo después de esta configuración?

No. La configuración conecta un proveedor externo de herramientas MCP. El flujo de trabajo que lo rodea sigue necesitando entradas válidas, una operación aprobada y una comprobación del resultado de la aplicación.

P: ¿Necesito una clave de API de CapSolver para ver Connected?

La conexión local probada tuvo éxito sin una operación de cuenta. Una resolución de pago necesita una clave válida y requisitos de cuenta aplicables; el estado Connected no valida ninguno de los dos.

P: ¿Por qué mi servidor MCP está deshabilitado en una carpeta desconocida?

La política de confianza en carpetas de Gemini CLI puede suprimir servidores MCP en un directorio que no es de confianza. Revisa la carpeta y sigue el flujo de confianza del cliente para el alcance previsto.

P: ¿Por qué la configuración expone solo dos herramientas?

El ejemplo permite la consulta de capacidades y la herramienta de resolución de tokens. Revisa la lista solo después de revisar otras herramientas, sus dependencias y su encaje en el flujo de trabajo.

P: ¿Una herramienta de resolución en página reutiliza mi pestaña de navegador existente?

No lo des por hecho. Comprueba el modelo de sesión documentado; una operación basada en URL y un objeto de página que posee tu programa de navegador son interfaces distintas.

P: ¿Qué debo probar después de que funcione la conexión MCP?

Prueba un flujo de trabajo extremo a extremo autorizado con credenciales válidas y un resultado observable de la aplicación. Registra el estado del solucionador por separado del resultado final de la página.