CaptchaNo MCP

Permite que los agentes de IA resuelvan reCAPTCHA v2/v3/Enterprise, Cloudflare Turnstile, DataDome y captchas de imagen a través de la API de CaptchaNo, con sondeo automático y un límite de gasto por sesión. Código abierto (MIT), se ejecuta con npx -y captchano-mcp.

GitHub

Documentación

Servidor MCP de CaptchaNo

El servidor oficial de Model Context Protocol para CaptchaNo. Permite que agentes de IA (Claude, Cursor, VS Code Copilot y cualquier otro cliente MCP) resuelvan reCAPTCHA v2 / v3 / Enterprise, Cloudflare Turnstile, DataDome y captchas de imagen mientras ejecutan automatización de navegador o HTTP.

Las resoluciones se ejecutan en la infraestructura de resolución propia de CaptchaNo y se facturan a tu saldo de CaptchaNo. Las resoluciones fallidas nunca se facturan.

Úsalo solo para automatización autorizada. Resuelve captchas únicamente en sitios que te pertenecen, sitios donde tengas permiso para automatizar, o sitios cuyos términos lo permitan (QA de tus propios formularios, accesibilidad, monitoreo de tus propias propiedades, investigación con permiso). Eres responsable de cómo lo uses.

Sitio web: https://captchano.com
Documentación de API: https://captchano.com/captcha-solver-api
Guía para agentes: https://captchano.com/agents/mcp
Soporte: support@captchano.com

Inicio rápido

Crea una clave de API en https://captchano.com/dashboard.. Las claves comienzan con cn-.
Agrega el servidor a tu cliente MCP (fragmentos abajo). Se ejecuta con npx -y captchano-mcp. Se requiere Node.js 20.3 o superior.
Pídele a tu agente algo como "Abre la página de registro, resuelve el captcha y envía el formulario."

Claude Code

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

Agrega --scope user para que esté disponible en todos los proyectos.

Claude Desktop

Edita claude_desktop_config.json (Configuración → Desarrollador → Editar configuración):

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

Cursor

~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto):

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

VS Code (modo agente de GitHub Copilot)

.vscode/mcp.json. VS Code solicita la clave la primera vez y la almacena de forma segura:

{
  "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 y otros clientes

Usa el mismo command / args / env que arriba: comando npx, argumentos ["-y", "captchano-mcp"], env CAPTCHANO_API_KEY.

Docker

docker build -t captchano-mcp .
docker run -i --rm -e CAPTCHANO_API_KEY=cn-... captchano-mcp

Configuración

Toda la configuración se lee de variables de entorno. La clave de API nunca se acepta como argumento de herramienta.

Variable	Requerida	Predeterminado	Descripción
`CAPTCHANO_API_KEY`	sí	–	Tu clave de API (`cn-...`).
`CAPTCHANO_MAX_SPEND_USD`	no	ilimitado	Límite de gasto para este proceso del servidor, en USD. Consulta Presupuesto.
`CAPTCHANO_WAIT`	no	`45`	Segundos que la API bloquea en cada solicitud de resolución (`?wait=N`, máximo 120) antes de que el servidor cambie a sondeo.
`CAPTCHANO_TOOL_TIMEOUT`	no	`50`	Máximo de segundos que una llamada a `solve_captcha` tarda antes de devolver un resultado reanudable de `solving`. Muchos clientes MCP cancelan llamadas de herramientas a los 60 s; aumenta esto solo si el tuyo permite más tiempo.
`CAPTCHANO_API_BASE`	no	`https://api.captchano.com`	URL base de la API.
`CAPTCHANO_MCP_HTTP_TOKEN`	no	–	En modo `--http`, requiere `Authorization: Bearer <token>` en `/mcp`.
`CAPTCHANO_LOG_LEVEL`	no	`info`	`debug`, `info`, `warn`, `error` o `silent`. Los registros van solo a stderr.

Herramientas

`solve_captcha`

Resuelve un captcha y devuelve el valor que la página necesita. Se factura por resolución exitosa.

Argumento	Tipos	Notas
`type`	todos	`recaptcha_v2`, `recaptcha_v3`, `recaptcha_enterprise`, `turnstile`, `datadome`, `image`
`url`	todos excepto `image`	URL completa de la página que muestra el captcha
`sitekey`	recaptcha_*, turnstile	De `data-sitekey`, el parámetro de iframe `k=` o el parámetro de script `render=`
`action`	recaptcha_v3, recaptcha_enterprise, turnstile	El nombre de la acción que usa la página
`minScore`	recaptcha_v3	0.1–0.9
`invisible`	recaptcha_v2, recaptcha_enterprise	`true` para widgets invisibles
`cData`, `pageData`	turnstile	`data-cdata`; `pageData` para páginas de desafío de Cloudflare
`challengeUrl`	datadome (requerido)	URL completa del captcha de la respuesta bloqueada
`proxy`	datadome (requerido), opcional para tipos de token	`"http://user:pass@host:port"` (http, socks4, socks5) o `{ scheme, host, port, username, password }`
`body`	image (requerido)	Imagen en Base64. Se acepta un prefijo `data:image/...;base64,`
`userAgent`	todos excepto image	El User-Agent del cliente que usará la solución

Cómo se ejecuta una llamada: el servidor envía POST /v1/solve?wait=N. Si la API responde 202 (aún resolviendo), el servidor sondea GET /v1/task/{id} cada 5 segundos, hasta 50 segundos en total por predeterminado (CAPTCHANO_TOOL_TIMEOUT). Si la tarea aún se está resolviendo después de eso, el resultado tiene status: "solving" y el id de la tarea, y el agente debe llamar a get_task con ese id en lugar de resolver de nuevo.

El resultado se devuelve como texto (token, cookie o texto, userAgent, costo, tiempo de resolución y el siguiente paso) y como structuredContent:

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

`get_task`

{ id } → el mismo objeto. Úsalo para reanudar una resolución que aún está solving, o para leer un resultado nuevamente. Las soluciones se conservan durante 10 minutos. Solo lectura y gratuito.

`get_balance`

Devuelve { balance, currency, sessionSpend }. Solo lectura y gratuito.

`list_captcha_types`

Una lista estática de cada tipo compatible: sus campos requeridos y opcionales, qué campo de solución devuelve, y una pista de una línea sobre dónde encontrar el sitekey (u otras entradas) en la página. No hace ninguna llamada de red.

Errores

Los errores de la API se devuelven como resultados de herramienta con isError: true. Cada uno incluye el código de error, el mensaje de la API y una pista sobre qué hacer a continuación. Por ejemplo:

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 de 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 de este servidor: invalid_arguments (detectado antes de enviar cualquier solicitud), budget_exhausted, network_error, timeout, cancelled, http_error.

Presupuesto

Establece CAPTCHANO_MAX_SPEND_USD para limitar cuánto puede gastar un proceso del servidor. El servidor suma los cost que la API devuelve por cada tarea que envió, contando cada tarea una vez. Una vez que el total alcanza el límite, solve_captcha devuelve budget_exhausted sin contactar a la API. get_task, get_balance y list_captcha_types siguen funcionando.

Notas:

El límite se aplica a cada proceso. Reiniciar el servidor o el cliente MCP lo restablece. Para un límite estricto a nivel de cuenta, mantén solo un saldo pequeño en la clave.
El límite se verifica antes de cada resolución. Una resolución que comienza justo por debajo del límite puede terminar ligeramente por encima, como máximo por el costo de las resoluciones ya en curso.

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

HTTP Streamable sin estado en /mcp, además de GET /healthz.
Se vincula a 127.0.0.1 por predeterminado. Usa --host 0.0.0.0 solo detrás de TLS y con CAPTCHANO_MCP_HTTP_TOKEN configurado: cualquiera que pueda alcanzar el endpoint puede gastar tu saldo.
La clave siempre proviene del entorno del servidor, nunca de los llamadores.

Seguridad

Claves: CAPTCHANO_API_KEY se lee solo del entorno. Nunca es un argumento de herramienta, nunca se incluye en resultados de herramientas y nunca se registra. Las líneas de registro también se depuran de cualquier cosa que parezca una clave cn-, un token de portador o credenciales de proxy.
stdout es el canal del protocolo. Todo el registro va a stderr.
Gasto: cada solve_captcha exitoso se factura. Usa CAPTCHANO_MAX_SPEND_USD y una clave dedicada con un saldo pequeño para agentes autónomos. La herramienta está anotada como una herramienta de mundo abierto que no es de solo lectura, por lo que los clientes que piden confirmación la solicitarán antes de ejecutarla.
Proxies: las credenciales de proxy se envían solo a la API de CaptchaNo, a través de HTTPS, y nunca se repiten en resultados o registros.
Inyección de prompts: una página que visita un agente puede intentar hacer que resuelva captchas en otros sitios. Mantén a un humano en el bucle para llamadas de resolución que no esperabas, y usa el límite de gasto.
Reporta vulnerabilidades a support@captchano.com.

Desarrollo

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 llama a get_balance contra la API real con una clave ficticia y espera un resultado limpio de invalid_api_key. Si CAPTCHANO_TEST_API_KEY está configurado, también ejecuta una resolución en vivo de la demostración pública de reCAPTCHA v2, con un límite de $0.05.