Solucionador de CAPTCHA de Claude Code: Guía de Configuración de CapSolver MCP

TL;DR

• Conecte Claude Code al paquete oficial capsolver-mcp para exponer las herramientas compatibles de resolución de CAPTCHA.
• Comience listando los tipos de CAPTCHA compatibles; una conexión exitosa de una herramienta no demuestra que una solicitud de resolución pagada tenga éxito.
• Use solve_captcha cuando ya tenga el tipo de desafío compatible, la URL de la página y el sitekey.
• Las herramientas de página abren su propia sesión del navegador; no continúan automáticamente una pestaña de navegador de Claude existente.
• Un token devuelto o un widget completado aún requiere la verificación final de la aplicación objetivo.

Claude Code puede ayudar a escribir o depurar una tarea de navegador, pero necesita una herramienta de resolución real cuando un CAPTCHA compatible interrumpe la operación aprobada. Pedirle al modelo que "intente más" no proporciona los parámetros del sitio, la conexión de la API o el manejo de resultados que requiere el desafío.

CapSolver expone estas capacidades a través de su servicio MCP. Esta guía cubre la instalación del paquete, la conexión con Claude Code, la verificación de las herramientas disponibles y la elección de una llamada de resolución. Los ejemplos se refieren a sus propias páginas o tareas de automatización permitidas. No automatizan la creación de cuentas, las compras o el acceso a datos restringidos.

¿Qué puede hacer Claude Code con CapSolver MCP?

Claude Code puede descubrir y llamar a las herramientas de CapSolver MCP después de configurar y aprobar el servidor.

El servicio MCP oficial https://docs.capsolver.com/en/guide/ai/mcp-service/ expone cinco herramientas:

Los nombres de las herramientas describen operaciones separadas. Una consulta de balance no reconoce una página, y detectar un widget no lo resuelve. Comience con la operación que realmente necesita.

La versión instalada verificada en esta guía, capsolver-mcp 0.1.3, listó reCaptchaV2, reCaptchaV3 y cloudflare a través de su herramienta de tipo compatible. En esta interfaz, el controlador de Cloudflare se refiere a Turnstile. No interprete el nombre como soporte universal para cada respuesta de Cloudflare o desafío de toda la página.

La API REST ofrece otras familias de tareas, pero no se agregan automáticamente al conjunto de herramientas MCP. En particular, no pase una tarea ImageToText a solve_captcha simplemente porque la API separada de CapSolver soporte reconocimiento de imágenes.

Instalar los paquetes oficiales

Instale el núcleo de CapSolver, el servidor MCP y las dependencias del navegador en el entorno de Python que lanzará Claude Code.

Los siguientes comandos fijan las versiones del núcleo y MCP utilizadas aquí:

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

La instalación sigue las instrucciones oficiales de CapSolver para los paquetes. El complemento del navegador y Chromium son necesarios para las herramientas de página. La guía de instalación del navegador Playwright explica que los binarios del navegador son una dependencia separada del paquete de Python.

Use el ejecutable de Python de este entorno en el siguiente paso. Si instala en un entorno virtual y configura un Python diferente, el cliente puede informar que no puede importar capsolver_mcp aunque la instalación haya tenido éxito en otro lugar.

También necesita Claude Code y una clave de cuenta de CapSolver para la resolución real. Almacene esa clave como CAPSOLVER_API_KEY en el entorno utilizado para iniciar Claude Code. No la pegue en un prompt de chat ni la comprometa en un archivo de proyecto compartido.

La conexión del paquete y la ruta de detección local pueden verificarse por separado de la resolución pagada. Esta guía no demuestra una resolución en vivo pagada; ese paso requiere su cuenta y los parámetros actuales de un objetivo aprobado.

Agregar CapSolver a la configuración MCP del proyecto

Agregue una entrada capsolver al archivo .mcp.json del proyecto, apuntando al entorno de Python donde instaló los paquetes.

La configuración siguiente utiliza el patrón documentado de módulo de Python de CapSolver y la expansión de variables de entorno de Claude Code. Reemplace la ruta del Python con la ruta absoluta real para su entorno:

{
  "mcpServers": {
    "capsolver": {
      "command": "/ruta/absoluta/a/venv/bin/python",
      "args": ["-m", "capsolver_mcp"],
      "env": {
        "CAPSOLVER_API_KEY": "${CAPSOLVER_API_KEY}"
      }
    }
  }
}

Si .mcp.json ya contiene otros servidores, agregue esta entrada dentro del objeto mcpServers existente en lugar de reemplazar el archivo. La clave se mantiene fuera del archivo JSON, pero la variable aún necesita estar disponible cuando se inicie Claude Code.

La documentación de configuración MCP de Claude Code cubre el alcance del proyecto, la expansión de variables de entorno y la aprobación del servidor. Inicie Claude Code desde el proyecto deseado, revise el aviso de aprobación del servidor del proyecto y apruebe este servidor solo después de confirmar que el comando y el paquete son los que instaló.

Verifique la configuración desde el directorio del proyecto:

claude mcp list

Dentro de una sesión interactiva de Claude Code, use /mcp para inspeccionar el estado del servidor y los controles disponibles. Un estado de aprobación pendiente significa que el servidor del proyecto aún necesita su revisión. Es diferente de un ejecutable faltante o una conexión fallida.

Verificar las herramientas antes de solicitar una resolución

Pida a Claude Code que liste los tipos de CAPTCHA compatibles antes de pedirle que gaste créditos de cuenta.

Una solicitud adecuada es:

Use la herramienta CapSolver get_supported_captchas y dígame qué tipos de CAPTCHA soporta actualmente este servidor. No envíe una tarea de resolución.

Esto confirma que el cliente puede alcanzar una herramienta real y le da la cobertura real del servidor instalado. La vida útil de conexión de MCP separa la inicialización de las operaciones posteriores; establecer la conexión es solo el comienzo de una integración útil.

Para una verificación de cuenta, puede solicitar get_balance. Mantenga la respuesta privada si contiene información de cuenta. Un fallo aquí apunta a acceso a la cuenta o comunicación de servicio y debe resolverse antes de intentar una resolución pagada.

No juzgue la preparación a partir de una declaración del modelo de que "sabe CapSolver". Inspeccione el resultado real de la herramienta. Una herramienta descubierta, una consulta exitosa de cuenta y una resolución de CAPTCHA completada establecen hechos diferentes.

Canjear su código de bonificación de CapSolver

Aumente su presupuesto de automatización instantáneamente!
Use el código de bonificación CAP26 al recargar su cuenta de CapSolver para obtener un 5% adicional en cada recarga — sin límites.
Canjéalo ahora en su Panel de CapSolver

Usar el modo de token para parámetros de desafío conocidos

Use solve_captcha cuando su flujo de navegador o aplicación aprobado ya proporcione los tipos requeridos, la URL de la página y el sitekey.

Por ejemplo, dé a Claude Code una instrucción limitada como:

Use la herramienta CapSolver solve_captcha una vez para el reCAPTCHA v2 en mi página de prueba aprobada. Use la URL de página y sitekey exactos que le proporcioné. Si alguno falta, informe que falta la entrada en lugar de adivinar. Devuelva el estado de la herramienta sin imprimir el token completo en su resumen.

El esquema de la herramienta utiliza captcha_type, website_url y website_key. Revise el esquema descubierto para verificar parámetros adicionales requeridos por el desafío que está manejando. No copie nombres de tareas de REST en el campo de tipo MCP: reCaptchaV2 es el valor MCP, mientras que la API REST tiene sus propios nombres de tarea documentados.

Su aplicación luego necesita consumir el token devuelto a través del flujo previsto del objetivo. La llamada MCP en sí misma no envía todos los formularios ni verifica un resultado comercial. Para entradas de reCAPTCHA específicas de página, consulte la documentación de tarea reCAPTCHA v2.

Si un parámetro es desconocido, inspeccione la página aprobada actual con las herramientas de navegador adecuadas. Un sitekey recordado de otra página no es evidencia para el widget actual. Mantenga la resolución conectada a la operación real que está depurando.

Usar herramientas de página con su límite de navegador en mente

Las herramientas de página aceptan una URL y operan en una sesión de navegador creada por el servicio MCP.

Para la detección, una solicitud útil es:

Llame a CapSolver detect_captchas en esta URL de página aprobada y reporte el tipo detectado. No lo resuelva aún.

Cuando resolver esa página sea la operación deseada, solve_on_page puede realizar su secuencia documentada de detección, resolución y relleno. Revise el desafío observado y la cobertura compatible antes de solicitar esa llamada.

La frontera importante es visible en la implementación oficial MCP: estas herramientas abren un navegador para la llamada y lo cierran después. No se adjuntan a una pestaña mantenida por un MCP de navegador separado ni heredan automáticamente su estado de inicio de sesión.

Esto hace que una página de prueba directa y alcanzable sea un punto de partida más claro que una página disponible solo después de varios pasos de sesión privada. Si su tarea necesita permanecer en una página de navegador que ya controla, use una integración compatible que opere en esa página existente. La documentación del SDK de CapSolver Core documenta las capacidades del adaptador de navegador para esa diferente necesidad de integración.

La guía Uso de ordenador de Claude discute una superficie de agente de navegador adyacente. El uso de ordenador de Claude y esta configuración MCP de Claude Code no deben tratarse como configuraciones intercambiables.

Corregir errores de configuración antes de repetir llamadas de CAPTCHA

La mayoría de los fallos de configuración pueden reducirse al camino del ejecutable, el entorno, la instalación del navegador o la entrada de tarea.

Si el comando del servidor no se encuentra, use la ruta absoluta del Python mostrada anteriormente. Si el paquete no se puede importar, verifique que el mismo entorno de Python contenga capsolver-mcp y capsolver-core.

Si la detección de página informa un ejecutable de navegador faltante, ejecute el comando de instalación de Chromium en el entorno que inicia el servidor MCP. El modo de token no requiere un navegador solo para llamar al servicio de resolución, por lo que distinga un fallo de inicio de navegador de un fallo de API de solucionador.

Si el servidor se conecta pero una llamada de API falla, conserve el código de error devuelto y un resumen redactado. Revise la clave de cuenta, el tipo compatible, los parámetros requeridos y el estado actual de la página antes de otro intento.

Si una resolución devuelve un token pero la aplicación original no cambia, inspeccione el consumo del resultado. Confirme que el resultado fue utilizado por el flujo previsto y que no asumió que dos sesiones de navegador separadas compartían estado.

Mantenga un límite pequeño en intentos repetidos. Cuando el mismo error permanezca sin resolver, devuelva la evidencia para revisión en lugar de instruir al agente para repetir indefinidamente.

Crear flujos de automatización confiables con CapSolver

Comience con una conexión MCP real, inspeccione el conjunto de herramientas instalado y solicite la operación que coincida con el desafío en su tarea aprobada.

CapSolver le da a Claude Code una capacidad documentada de resolución de CAPTCHA. Entradas correctas y un límite claro de navegador hacen que esa capacidad sea útil; la respuesta de la aplicación final le dice si la tarea deseada realmente se completó.

Preguntas frecuentes

P: ¿Necesito dependencias de navegador para cada herramienta MCP?

No. Las herramientas de página necesitan el complemento del navegador y Chromium. La resolución de token y las consultas de cuenta o cobertura no necesitan abrir un navegador solo para llamar a su servicio correspondiente o capacidad local.

P: ¿Puede continuar CapSolver MCP mi pestaña de navegador existente?

Las herramientas de página en la versión revisada abren y cierran su propia sesión de navegador. No asuma que controlan una pestaña propiedad de otra herramienta de navegador.

P: ¿El servidor MCP admite cada tarea de REST de CapSolver?

No. Revise get_supported_captchas y el esquema de herramienta descubierto. Las capacidades separadas de REST no se exponen automáticamente a través de este paquete MCP.

P: ¿Por qué muestra Claude Code aprobación pendiente?

Un servidor MCP de proyecto puede requerir aprobación antes de su uso. Revíselo en Claude Code y confirme el comando configurado en lugar de tratar el estado de aprobación como un error de clave de API.

P: ¿Significa una resolución exitosa que el agente terminó su tarea?

No. Verifique que el resultado fue consumido por la aplicación prevista y que la operación de página solicitada se completó. Un token o widget completado es un resultado intermedio.