2Captcha MCP

2Captcha MCP: herramientas para agentes de IA, scraping web y automatización de navegadores

Scraping web con evasión anti-bot, análisis de marketplaces a JSON estructurado y resolución de CAPTCHA para agentes de IA mediante el Protocolo de Contexto de Modelo.

Funciona con Claude, Cursor, agentes de codificación y cualquier cliente compatible con MCP.

Cuota mensual gratuita en cada cuenta — regístrate, añade tu clave de API y las primeras 200 llamadas al mes corren de nuestra cuenta. Qué incluye

Plan gratuito • Inicio rápido • Instalación • Grupos de herramientas • Herramientas • Configuración • Solución de problemas

English • Русский

https://github.com/user-attachments/assets/884d89a8-3a73-495b-9649-dca282a70369

_{Codex desktop, mismo modelo y prompt, grabados uno tras otro · velocidad 3×}

[!IMPORTANT] El paquete oficial de 2Captcha MCP es @2captcha/mcp (publicado bajo la organización npm @2captcha). El paquete 2captcha-mcp sin ámbito en npm no está afiliado a 2Captcha — no pongas tu clave de API en él.

Resumen

El servidor MCP de 2Captcha ofrece a los agentes de IA acceso en tiempo real a datos web que bloquean a los clientes HTTP ordinarios. Expone 40 herramientas que cubren:

• Búsqueda web — resultados orgánicos clasificados (título, URL, fragmento) para una consulta
• Scraping de páginas — cualquier URL como Markdown limpio o HTML sin procesar. Cada solicitud pasa por una escalera anti-bot por niveles: APIs JSON ocultas, un cliente HTTP que imita TLS, proxies residenciales rotativos y un navegador gestionado con resolución de CAPTCHA — escalando solo hasta donde la página lo requiera, para que las páginas fáciles sigan siendo rápidas y económicas.
• Análisis de marketplaces — páginas de producto y listados de búsqueda como JSON estructurado (título, precio, valoración, vendedor, stock, ofertas). Primero niveles deterministas (APIs ocultas del marketplace, JSON-LD, selectores aprendidos); una pasada de extracción con LLM solo cuando fallan.
• Extracción estructurada — cualquier URL o texto sin procesar más tu propio esquema JSON de entrada, JSON coincidente de salida.
• Trabajos por lotes — ejecuta las herramientas de scraping/análisis sobre muchas URLs como un trabajo en segundo plano: envía, consulta, cancela.
• Resolución de CAPTCHA, incluso en tu navegador — resuelve cualquier tipo que 2Captcha soporte (reCAPTCHA, Turnstile, hCaptcha, DataDome, imágenes, …). detect_captcha nombra el muro en una página que ya estás manejando en Playwright MCP, browser-use o una extensión — gratis, desde HTML que pegues — y solve_captcha_on_page lo resuelve y devuelve el JavaScript o la cookie exacta para aplicar en tu propia sesión. Nada tiene que moverse a nuestro navegador.
• Inicios de sesión en navegador — opcional. Inicia sesión en un sitio cuyo formulario de acceso está detrás de un CAPTCHA, en un navegador gestionado, y guarda la sesión para más tarde.

Dos opciones de despliegue: el servidor remoto alojado (una URL, sin instalación) o una instancia local mediante npx @2captcha/mcp.

Plan gratuito: qué incluye

Registrarse en 2Captcha es gratis, y una cuenta viene con una cuota mensual en este servidor: 200 llamadas o $0.50 de gasto medido por cada 30 días, lo que ocurra primero, en toda la superficie de herramientas — scraping, análisis de marketplaces, extracción estructurada, trabajos por lotes, herramientas de navegador y resolución de CAPTCHA. Sin tarjeta, sin plan separado, sin restricciones de funciones.

La ventana es móvil en lugar de mensual-calendario, por lo que la capacidad regresa continuamente en lugar de que la cuota de todos se reinicie el día 1.

La cuota se mide por cuenta, por eso se requiere una credencial: la identidad es contra lo que se cuenta. No hay modo anónimo — una dirección IP no es una identidad, y un plan gratuito vinculado a una es un plan gratuito vinculado a un grupo de proxies.

get_account informa de lo que queda, para que un agente pueda planificar en torno al límite en lugar de descubrirlo como un fallo a mitad de una tarea:

{"tenant": "2captcha:8f14e45fceea167a",
 "free_tier": {"allowance": {"max_calls": 200, "calls": 12, "remaining_calls": 188,
                             "max_spend_usd": 0.5, "remaining_spend_usd": 0.4871,
                             "window_hours": 720}}}

Nada más en este servidor factura por llamada: las resoluciones de CAPTCHA se cargan a tu saldo de 2Captcha como siempre se hizo, y include_meta: true informa de lo que realmente costó cualquier llamada. Así que cuando la cuota se agota, las llamadas se rechazan hasta que la ventana se rellena — el mensaje lo dice, y dice que el operador puede aumentarla. ¿Necesitas más que la cuota? Habla con el operador; en el servicio alojado eso es soporte de 2Captcha.

Inicio rápido

Servidor alojado — sin instalación

Añade la URL a tu cliente MCP con una cabecera Authorization:

URL:    https://mcp.2captcha.com/mcp
Header: Authorization: Bearer YOUR_API_TOKEN

Tu token es tu clave de API de 2Captcha (configuración de la cuenta) o el token de portador que emitió el operador de tu servidor. Registrarse es gratis y trae la cuota mensual consigo.

Servidor local mediante npx

{
  "mcpServers": {
    "2captcha": {
      "command": "npx",
      "args": ["@2captcha/mcp"],
      "env": {
        "API_TOKEN": "<your-api-token-here>"
      }
    }
  }
}

El servidor local refleja la superficie de herramientas alojada a través de stdio — úsalo con clientes que no pueden enviar cabeceras de autenticación o que solo lanzan servidores MCP locales.

Instalación

Cada cliente de abajo necesita las mismas dos cosas: el comando npx @2captcha/mcp con API_TOKEN en su entorno, o — donde el cliente hable HTTP — la URL alojada más una cabecera Authorization: Bearer. Obtén un token en 2captcha.com/setting; registrarse es gratis y trae la cuota mensual consigo.

claude mcp add --transport http 2captcha https://mcp.2captcha.com/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN"

claude mcp add 2captcha -e API_TOKEN=YOUR_API_TOKEN -- npx @2captcha/mcp

{
  "mcpServers": {
    "2captcha": {
      "command": "npx",
      "args": ["@2captcha/mcp"],
      "env": { "API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}

{
  "mcpServers": {
    "2captcha": {
      "command": "npx",
      "args": ["@2captcha/mcp"],
      "env": { "API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}

codex mcp add 2captcha --env API_TOKEN=YOUR_API_TOKEN -- npx @2captcha/mcp

[mcp_servers.2captcha]
command = "npx"
args = ["@2captcha/mcp"]
env = { API_TOKEN = "YOUR_API_TOKEN" }

{
  "servers": {
    "2captcha": {
      "command": "npx",
      "args": ["@2captcha/mcp"],
      "env": { "API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}

API_TOKEN=YOUR_API_TOKEN npx @modelcontextprotocol/inspector npx @2captcha/mcp

{
  "mcpServers": {
    "2captcha": {
      "command": "npx",
      "args": ["@2captcha/mcp"],
      "env": { "API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}

{
  "context_servers": {
    "2captcha": {
      "source": "custom",
      "command": "npx",
      "args": ["@2captcha/mcp"],
      "env": { "API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}

{
  "2captcha": {
    "command": "npx",
    "args": ["@2captcha/mcp"],
    "env": { "API_TOKEN": "YOUR_API_TOKEN" },
    "start_on_launch": true
  }
}

{
  "mcpServers": {
    "2captcha": {
      "command": "npx",
      "args": ["@2captcha/mcp"],
      "env": { "API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}

{
  "mcpServers": {
    "2captcha": {
      "command": "npx",
      "args": ["@2captcha/mcp"],
      "env": { "API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}

{
  "mcpServers": {
    "2captcha": {
      "url": "https://mcp.2captcha.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
    }
  }
}

qwen mcp add 2captcha -e API_TOKEN=YOUR_API_TOKEN npx @2captcha/mcp

qwen mcp add --transport http 2captcha https://mcp.2captcha.com/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN"

{
  "mcpServers": {
    "2captcha": {
      "command": "npx",
      "args": ["@2captcha/mcp"],
      "env": { "API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}

- id: mcp-2captcha
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: 2captcha
    transport: stdio
    command: npx
    args: ['@2captcha/mcp']
    env:
      API_TOKEN: !!js process.env.API_TOKEN

- id: mcp-2captcha
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: 2captcha
    transport: streamable-http
    url: https://mcp.2captcha.com/mcp
    headers:
      Authorization: !!js '`Bearer ${process.env.API_TOKEN}`'

"tools": [
  {
    "type": "mcp",
    "mcp": {
      "server_label": "2captcha",
      "server_url": "https://mcp.2captcha.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
    }
  }
]

mcpServers:
  - name: 2captcha
    command: npx
    args:
      - "@2captcha/mcp"
    env:
      API_TOKEN: YOUR_API_TOKEN

{
  "mcpServers": {
    "2captcha": {
      "command": "npx",
      "args": ["@2captcha/mcp"],
      "env": { "API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}

{
  "mcpServers": {
    "2captcha": {
      "command": "npx",
      "args": ["@2captcha/mcp"],
      "env": { "API_TOKEN": "YOUR_API_TOKEN" },
      "disabled": false
    }
  }
}

goose session --with-extension "npx @2captcha/mcp"

Endpoint:       https://mcp.2captcha.com/mcp
Transport:      HTTP Streamable
Authentication: Header Auth
Header name:    Authorization
Header value:   Bearer YOUR_API_TOKEN

command: npx
args:    ["@2captcha/mcp"]
env:     API_TOKEN=YOUR_API_TOKEN

docker run --rm -i -e API_TOKEN=YOUR_API_TOKEN ghcr.io/2captcha/2captcha-mcp:latest

{
  "mcpServers": {
    "2captcha": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "API_TOKEN", "ghcr.io/2captcha/2captcha-mcp:latest"],
      "env": { "API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}

Pruébalo

Pregunta a tu agente:

Analiza https://www.wildberries.ru/catalog/0/search.aspx?search=coffee como resultados de búsqueda y lista los cinco artículos más baratos.

Extrae https://news.ycombinator.com y resume las historias principales.

¿Cuál es mi saldo de 2Captcha?

Selección de herramientas: Grupos

Por defecto, el servidor expone los grupos de análisis, lote y captcha (17 herramientas). Los grupos de navegador son opcionales: son la única parte de la superficie que cuesta a un cliente contexto real en cada turno, y la mayoría de las tareas nunca lo tocan.

Costo medido de cada grupo, como las definiciones de herramientas que un cliente pone en cada solicitud (nombre + descripción + JSON Schema, tiktoken o200k_base — regenerar con el repositorio de servicios benchmarks/scripts/tool_surface_tokens.py):

Por qué captcha es un predeterminado y browser no. detect_captcha y solve_captcha_on_page funcionan en HTML desde cualquier navegador que ya estés manejando, por lo que son útiles para un cliente que nunca abre el nuestro — que es el caso común. Ver Manejando tu propio navegador.

Ejemplos de configuración

{
  "mcpServers": {
    "2captcha": {
      "command": "npx",
      "args": ["@2captcha/mcp"],
      "env": {
        "API_TOKEN": "YOUR_API_TOKEN",
        "GROUPS": "parsing,browser"
      }
    }
  }
}

Herramientas individuales, sin grupos:

"env": {
  "API_TOKEN": "YOUR_API_TOKEN",
  "TOOLS": "scrape_page,solve_captcha"
}

GROUPS y TOOLS se combinan (unión). La disponibilidad de herramientas es en última instancia la decisión del servidor — un grupo nombrado aquí solo filtra lo que el servidor realmente anuncia.

Referencia de herramientas (40 herramientas)

Qué herramienta usar

• ¿Buscas páginas para extraer? → search_web (consulta → URL clasificadas)
• ¿Solo necesitas el contenido de la página? → scrape_page (sin LLM, más barato)
• ¿Necesitas un inventario de URL antes de procesar en lote? → discover_urls (robots.txt + sitemaps, sin rastreo)
• ¿Construyendo una URL de búsqueda para un sitio? → discover_search_params (sus nombres de parámetros reales, no una suposición)
• ¿Página de producto o búsqueda → JSON? → parse_marketplace (niveles deterministas primero, respaldo LLM)
• ¿Tu propio esquema desde cualquier página/texto? → extract (siempre una llamada LLM, o caché)
• ¿Muchas URL? → scrape_pages / parse_pages + get_job
• ¿Encontraste un CAPTCHA en tu propio navegador? → detect_captcha (gratis) luego solve_captcha_on_page
• ¿Un token CAPTCHA para tu propia automatización? → list_captcha_types luego solve_captcha
• ¿Iniciar sesión pasando un CAPTCHA y mantener la sesión? → GROUPS=browser, luego browser_navigate → browser_fill → browser_click → browser_save_session

Análisis

Trabajos en lote

Manejando tu propio navegador (recomendado)

Si ya tienes un navegador — Playwright MCP, browser-use, una extensión de Chrome, tu propio script de Playwright — consérvalo, y usa estas dos herramientas para la parte que necesita una cuenta de solucionador:

your browser hits a wall
  -> browser_get_html / page.content()      your session, your IP
  -> detect_captcha(url, html=...)          free: "recaptcha, sitekey 6Lc..., solvable"
  -> solve_captcha_on_page(url, html=...)   one solve
  -> run apply.javascript in your page      returns 'callback' / 'submit' / 'set'

apply.javascript es una expresión completa con el token ya incluido — es el mismo inyector que usa el nivel de renderizado de este servicio — por lo que se inserta directamente en page.evaluate, una consola de devtools, o cualquier herramienta de ejecutar-JS. Cuando la respuesta es una cookie en su lugar (DataDome, AWS WAF) obtienes la cookie analizada y la instrucción de volver a solicitar en lugar de recargar.

Dos cosas que vale la pena saber. Pasa html desde tu navegador, porque los muros anti-bot se levantan por cliente y nuestra dirección ve una página diferente a la tuya. Y para DataDome o CaptchaFox pasa tu propio proxy y user_agent: esas respuestas se acuñan para la identidad que las resolvió, por lo que una resuelta como nosotros se rechaza en tu sesión aunque sea técnicamente correcta.

Inicios de sesión en navegador (GROUPS=browser, 11 herramientas)

El navegador gestionado no intenta superar a Playwright. Esa superficie es gratuita y probablemente ya la tienes, y esta mantiene una página en vivo por cuenta, por lo que es la herramienta equivocada para cualquier cosa paralela. Lo que tiene que un navegador normal no tiene es que resuelve el CAPTCHA en el formulario de inicio de sesión, y puede mantener las cookies después — por lo que el grupo se limita exactamente a eso, a 2,842 tokens en lugar de 5,201:

Establece GROUPS=browser_full para la superficie completa de 23 herramientas — añadiendo historial (browser_go_back, browser_go_forward, browser_reload), browser_scroll, browser_select_option, browser_hover, browser_drag, browser_console_messages, browser_evaluate, browser_snapshot_items, browser_screenshot y browser_save_as_pdf.

CAPTCHA

Local

Configuración

Variables de entorno

MAX_SPEND_USD es el que vale la pena configurar si solo configuras uno. Un límite de llamadas acota la cantidad equivocada — un solo parse_pages sobre 500 URL cuesta más que cien llamadas scrape_page — por lo que RATE_LIMIT te protege de un bucle descontrolado mientras MAX_SPEND_USD te protege de una factura descontrolada. El costo de una llamada solo se conoce una vez que el servidor responde, por lo que el límite se verifica contra lo que ya se ha gastado: acota el exceso a una llamada en lugar de pretender ser exacto.

Línea de comandos

npx @2captcha/mcp --version
npx @2captcha/mcp --help      # every variable above, with its default

Qué sale de tu máquina

Vale la pena aclarar esto antes de que llegue a una revisión de seguridad, porque la respuesta honesta es "más que una herramienta local, menos que una extensión de navegador".

A dónde va. Un lugar: MCP_URL — https://mcp.2captcha.com/mcp a menos que lo apuntes a tu propio servidor. Sin telemetría, sin análisis, sin terceros. El puente no abre ningún puerto de escucha. Qué viaja con una llamada de herramienta. Los argumentos de esa herramienta, reenviados textualmente y ni inspeccionados ni registrados por el puente. Para scrape_page eso es una URL. Para detect_captcha y solve_captcha_on_page es el HTML de la página que pasas — y el HTML tomado de una sesión iniciada contiene lo que esa página contenga. Para extract es tu esquema y cualquier texto que proporciones directamente.

Tu token de API va a MCP_URL como token de portador y a ningún otro lugar. Este paquete nunca lo escribe en disco.

Lo que almacenan los grupos de navegador. browser y browser_full controlan un navegador en el servidor, y browser_save_session mantiene deliberadamente las cookies de ese navegador en el lado del servidor para que una ejecución posterior pueda omitir el inicio de sesión. Esa es la característica, y también es la parte en la que pensar más detenidamente: una sesión guardada es una credencial viva para ese sitio, retenida por nosotros. browser_list_sessions muestra lo que existe. Ambos grupos son opcionales y están desactivados por defecto.

Las herramientas de CAPTCHA del lado de la página — detect_captcha y solve_captcha_on_page, ambas activadas por defecto — existen en parte para evitar esto. Leen el HTML de tu navegador y devuelven el JavaScript o la cookie para aplicar en tu sesión, de modo que la sesión nunca se mueve.

Lo que permanece en tu máquina. Un archivo: la caché offline de la lista de herramientas — nombres de herramientas y esquemas JSON, claveados por endpoint, bajo CACHE_DIR (por defecto ~/Library/Caches/2captcha-mcp en macOS, $XDG_CACHE_HOME/2captcha-mcp en Linux, %LOCALAPPDATA%\2captcha-mcp en Windows). Sin argumentos, sin resultados, sin credenciales. Eliminarlo cuesta un viaje de ida y vuelta en el próximo inicio.

Retención y eliminación. Los datos de solicitud se retienen en el lado del servidor según la política de privacidad de 2Captcha. Para eliminar una sesión de navegador almacenada, cárgala y límpiala, o contacta con support@2captcha.com. Para eliminar todo lo local, borra el directorio de caché; para invalidar el acceso, rota tu clave en 2captcha.com/setting.

Cómo funciona

Este paquete es un puente stdio delgado hacia el servicio remoto: los esquemas de herramientas se obtienen en vivo del servidor y se mantienen durante 60 segundos, de modo que el paquete nunca se desvía de la superficie de herramientas implementada, y las nuevas herramientas del lado del servidor aparecen automáticamente bajo GROUPS=all. Las llamadas se reenvían textualmente — incluyendo structuredContent, imágenes (capturas de pantalla) y errores de herramientas — con reconexión automática si la conexión se cae a mitad de sesión, y reintentos con retroceso exponencial en respuestas 429 y 5xx, respetando Retry-After.

Se inicia tanto si la red funciona como si no. La lista de herramientas se almacena en caché en disco, de modo que un portátil que se despierta con Wi-Fi muerto aún registra un servidor funcional y repuebla sus herramientas por notificación una vez que la conexión vuelve — en lugar de que el cliente marque el servidor como roto hasta que lo reinicies manualmente. El único fallo con el que se niega a iniciar es un token rechazado, porque ese no se arreglará solo.

Los costos se miden en el lado del servidor contra tu token: el scraping gasta recursos de proxy/navegador, solve_captcha gasta una resolución por llamada, y la extracción LLM en parse_marketplace/extract factura tu propia clave LLM cuando tienes una guardada (BYOK), el valor predeterminado del servidor en caso contrario. Pasa include_meta: true a las herramientas de análisis para ver exactamente qué gastó una llamada — este servicio es el único que informa el precio de una llamada al agente que la realiza, en lugar de solo en un panel después.

La asignación de nivel gratuito funciona con ese mismo medidor, vinculado a tu cuenta en su propia ventana de 30 días — por eso get_account puede decirte exactamente cuántas llamadas y cuánto gasto te queda.

Solución de problemas

"Cannot run without the API_TOKEN env"

Establece API_TOKEN en el bloque env de la configuración de tu cliente con tu clave API de 2Captcha (https://2captcha.com/setting). La asignación gratuita se mide por cuenta, por lo que necesita la credencial — registrarse es gratis.

"Authentication to … failed"

El servidor rechazó el token. Verifica si hay espacios en blanco y confirma qué credencial acepta tu implementación (clave API de 2Captcha vs. un token emitido por el operador).

"has used N of N calls allowed per 720h"

La asignación mensual de tu cuenta está agotada. La ventana es móvil, por lo que la capacidad regresa a medida que las llamadas más antiguas caducan; get_account muestra cuánto queda y cuándo. En un servidor autoalojado, el operador aumenta WEBPARSE_FREE_TIER_MAX_CALLS / WEBPARSE_FREE_TIER_MAX_SPEND_USD, o exime la cuenta por completo.

"is outside this server's allowance, which covers: …"

El operador restringió la asignación a un subconjunto de herramientas (WEBPARSE_FREE_TIER_TOOLS). Esa es una restricción de todo el servidor, no algo que una credencial diferente levante — pídeles que la amplíen. get_account enumera las herramientas a las que tu cuenta puede acceder.

"spawn npx ENOENT"

Tu cliente MCP no puede encontrar Node. Instala Node.js ≥ 18 y asegúrate de que npx esté en el PATH que usa el cliente (en aplicaciones GUI de macOS, usa una ruta absoluta a npx).

Tiempos de espera en sitios difíciles

Las páginas que fuerzan la escalera completa (navegador gestionado + resolución de CAPTCHA) pueden tardar minutos. Aumenta POLLING_TIMEOUT (segundos) y prefiere scrape_pages/parse_pages para muchas URLs para que la espera ocurra en el lado del servidor.

Falta una herramienta que espero

El valor predeterminado expone parsing,batch,captcha. Para una herramienta de navegador, establece GROUPS=browser (las 11 herramientas de inicio de sesión) o GROUPS=browser_full (las 23); GROUPS=all desactiva el filtrado por completo. Si aún falta, el servidor mismo tiene ese conjunto de herramientas deshabilitado — o el operador restringió la asignación a un subconjunto de herramientas (get_account lo dirá).

Licencia

MIT — © 2Captcha. Ver LICENSE.