2Captcha MCP

2Captcha MCP: ferramentas para agentes de IA, raspagem web e automação de navegador

Raspagem web com bypass anti-bot, parsing de marketplaces para JSON estruturado e resolução de CAPTCHA para agentes de IA via Model Context Protocol.

Funciona com Claude, Cursor, agentes de codificação e qualquer cliente compatível com MCP.

Franquia mensal gratuita em toda conta — cadastre-se, adicione sua chave de API e as primeiras 200 chamadas por mês são por nossa conta. O que está incluído

Plano Gratuito • Início Rápido • Instalação • Grupos de Ferramentas • Ferramentas • Configuração • Solução de Problemas

Inglês • Russo

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

_{Codex desktop, mesmo modelo e prompt, gravados um após o outro · velocidade 3×}

[!IMPORTANT] O pacote oficial 2Captcha MCP é @2captcha/mcp (publicado sob a organização npm @2captcha). O pacote 2captcha-mcp sem escopo no npm não é afiliado à 2Captcha — não coloque sua chave de API nele.

Visão Geral

O servidor MCP 2Captcha dá aos agentes de IA acesso em tempo real a dados web que bloqueiam clientes HTTP comuns. Ele expõe 40 ferramentas que cobrem:

• Pesquisa web — resultados orgânicos ranqueados (título, URL, trecho) para uma consulta
• Raspagem de páginas — qualquer URL como Markdown limpo ou HTML bruto. Cada requisição passa por uma escada anti-bot em camadas: APIs JSON ocultas, um cliente HTTP com impersonação de TLS, proxies residenciais rotativos e um navegador gerenciado com resolução de CAPTCHA — escalando apenas até onde a página exige, para que páginas fáceis permaneçam rápidas e baratas.
• Parsing de marketplaces — páginas de produto e listagens de busca como JSON estruturado (título, preço, avaliação, vendedor, estoque, ofertas). Camadas determinísticas primeiro (APIs ocultas de marketplace, JSON-LD, seletores aprendidos); uma passagem de extração com LLM apenas quando elas falham.
• Extração estruturada — qualquer URL ou texto bruto mais seu próprio JSON Schema na entrada, JSON correspondente na saída.
• Trabalhos em lote — execute as ferramentas de raspagem/parsing sobre muitas URLs como um trabalho em segundo plano: envie, consulte, cancele.
• Resolução de CAPTCHA, inclusive no seu navegador — resolva qualquer tipo que a 2Captcha suporta (reCAPTCHA, Turnstile, hCaptcha, DataDome, imagens, …). detect_captcha nomeia a barreira em uma página que você já está dirigindo no Playwright MCP, browser-use ou uma extensão — grátis, a partir de HTML que você cola — e solve_captcha_on_page resolve e devolve o JavaScript ou cookie exato para aplicar na sua própria sessão. Nada precisa ser movido para o nosso navegador.
• Logins em navegador — opcional. Entre em um site cujo formulário de login está atrás de um CAPTCHA, em um navegador gerenciado, e salve a sessão para depois.

Duas opções de implantação: o servidor remoto hospedado (uma URL, sem instalação) ou uma instância local via npx @2captcha/mcp.

Plano gratuito: o que está incluído

Cadastrar-se na 2Captcha é grátis, e uma conta vem com uma franquia mensal neste servidor: 200 chamadas ou $0,50 de gasto medido por 30 dias, o que ocorrer primeiro, em toda a superfície de ferramentas — raspagem, parsing de marketplace, extração estruturada, trabalhos em lote, ferramentas de navegador e resolução de CAPTCHA. Sem cartão, sem plano separado, sem bloqueio de recursos.

A janela é contínua em vez de mensal por calendário, então a capacidade retorna continuamente em vez de a cota de todos ser redefinida no dia 1º.

A franquia é medida por conta, e é por isso que uma credencial é necessária: a identidade é contra o que ela é contabilizada. Não há modo anônimo — um endereço IP não é uma identidade, e um plano gratuito vinculado a um é um plano gratuito vinculado a um pool de proxies.

get_account relata o que resta, para que um agente possa planejar em torno do limite em vez de descobri-lo como uma falha no meio de uma tarefa:

{"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 mais neste servidor cobra por chamada: resoluções de CAPTCHA são cobradas do seu saldo 2Captcha como sempre foram, e include_meta: true relata o que qualquer chamada realmente custou. Então, quando a franquia acaba, chamadas são recusadas até a janela reabastecer — a mensagem diz isso, e diz que o operador pode aumentá-la. Precisa de mais do que a franquia? Fale com o operador; no serviço hospedado isso é o suporte 2Captcha.

Início Rápido

Servidor hospedado — sem instalação

Adicione a URL ao seu cliente MCP com um cabeçalho Authorization:

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

Seu token é sua chave de API 2Captcha (configurações da conta) ou o token bearer emitido pelo operador do seu servidor. Cadastrar-se é grátis e traz a franquia mensal junto.

Servidor local via npx

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

O servidor local espelha a superfície de ferramentas hospedada via stdio — use-o com clientes que não podem enviar cabeçalhos de autenticação ou que só iniciam servidores MCP locais.

Instalação

Cada cliente abaixo precisa das mesmas duas coisas: o comando npx @2captcha/mcp com API_TOKEN em seu ambiente, ou — onde o cliente fala HTTP — a URL hospedada mais um cabeçalho Authorization: Bearer. Obtenha um token em 2captcha.com/setting; cadastrar-se é grátis e traz a franquia mensal junto.

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

Experimente

Pergunte ao seu agente:

Analise https://www.wildberries.ru/catalog/0/search.aspx?search=coffee como resultados de busca e liste os cinco itens mais baratos.

Raspe https://news.ycombinator.com e resuma as principais notícias.

Qual é o meu saldo no 2Captcha?

Seleção de Ferramentas: Grupos

Por padrão, o servidor expõe os grupos parsing, batch e captcha (17 ferramentas). Os grupos de navegador são opcionais: eles são a única parte da superfície que custa ao cliente contexto real a cada turno, e a maioria das tarefas nunca os utiliza.

Custo medido de cada grupo, conforme as definições de ferramentas que um cliente envia em cada requisição (nome + descrição + JSON Schema, tiktoken o200k_base — regenere com o repositório de serviço benchmarks/scripts/tool_surface_tokens.py):

Por que captcha é padrão e browser não é. detect_captcha e solve_captcha_on_page funcionam em HTML de qualquer navegador que você já está dirigindo, então são úteis para um cliente que nunca abre o nosso — que é o caso comum. Veja Dirigindo seu próprio navegador.

Exemplos de configuração

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

Ferramentas individuais, sem grupos:

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

GROUPS e TOOLS combinam (união). A disponibilidade de ferramentas é, em última análise, uma decisão do servidor — um grupo nomeado aqui apenas filtra o que o servidor realmente anuncia.

Referência de Ferramentas (40 Ferramentas)

Qual ferramenta usar

• Procurando páginas para raspar? → search_web (consulta → URLs classificadas)
• Só precisa do conteúdo da página? → scrape_page (sem LLM, mais barato)
• Precisa de um inventário de URLs antes de agrupar? → discover_urls (robots.txt + sitemaps, sem rastreamento)
• Construindo uma URL de busca para um site? → discover_search_params (os nomes reais dos parâmetros, não um palpite)
• Página de produto ou busca → JSON? → parse_marketplace (níveis determinísticos primeiro, fallback LLM)
• Seu próprio esquema de qualquer página/texto? → extract (sempre uma chamada LLM, ou cache)
• Muitas URLs? → scrape_pages / parse_pages + get_job
• Encontrou um CAPTCHA no seu próprio navegador? → detect_captcha (grátis) depois solve_captcha_on_page
• Um token CAPTCHA para sua própria automação? → list_captcha_types depois solve_captcha
• Fazer login atrás de um CAPTCHA e manter a sessão? → GROUPS=browser, depois browser_navigate → browser_fill → browser_click → browser_save_session

Parsing

Trabalhos em lote

Dirigindo seu próprio navegador (recomendado)

Se você já tem um navegador — Playwright MCP, browser-use, uma extensão Chrome, seu próprio script Playwright — mantenha-o, e use estas duas ferramentas para a parte que precisa de uma conta de solver:

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 é uma expressão completa com o token já embutido — é o mesmo injetor que o nível de renderização deste serviço usa — então ele se encaixa diretamente em page.evaluate, um console devtools, ou qualquer ferramenta de execução de JS. Quando a resposta é um cookie (DataDome, AWS WAF), você recebe o cookie analisado e a instrução para re-requisitar em vez de recarregar.

Duas coisas que valem a pena saber. Passe html do seu navegador, porque paredes anti-bot são levantadas por cliente e nosso endereço vê uma página diferente da sua. E para DataDome ou CaptchaFox, passe seu próprio proxy e user_agent: essas respostas são cunhadas para a identidade que as resolveu, então uma resolvida como nós é recusada na sua sessão, mesmo que seja tecnicamente correta.

Logins de navegador (GROUPS=browser, 11 ferramentas)

O navegador gerenciado não está tentando superar o Playwright. Essa superfície é gratuita e você provavelmente já a tem, e esta mantém uma página viva por conta, então é a ferramenta errada para qualquer coisa paralela. O que ela tem que um navegador comum não tem é que resolve o CAPTCHA no formulário de login e pode manter os cookies depois — então o grupo é limitado exatamente a isso, a 2.842 tokens em vez de 5.201:

Defina GROUPS=browser_full para a superfície completa de 23 ferramentas — adicionando histórico (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 e browser_save_as_pdf.

CAPTCHA

Local

Configuração

Variáveis de ambiente

MAX_SPEND_USD é o que vale a pena definir se você definir apenas um. Um limite de chamadas limita a quantidade errada — um único parse_pages sobre 500 URLs custa mais do que cem chamadas scrape_page — então RATE_LIMIT protege você de um loop descontrolado enquanto MAX_SPEND_USD protege você de uma conta descontrolada. O custo de uma chamada só é conhecido quando o servidor responde, então o limite é verificado contra o que já foi gasto: ele limita o excesso a uma chamada em vez de fingir ser exato.

Linha de comando

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

O que sai da sua máquina

Vale a pena resolver antes que isso chegue a uma revisão de segurança, porque a resposta honesta é "mais do que uma ferramenta local, menos do que uma extensão de navegador".

Para onde vai. Um lugar: MCP_URL — https://mcp.2captcha.com/mcp a menos que você aponte para seu próprio servidor. Sem telemetria, sem análises, sem terceiros. A ponte não abre porta de escuta. O que acompanha uma chamada de ferramenta. Os argumentos dessa ferramenta, encaminhados literalmente e nem inspecionados nem registrados pela ponte. Para scrape_page, isso é uma URL. Para detect_captcha e solve_captcha_on_page, é o HTML da página que você envia — e HTML obtido de uma sessão autenticada contém o que essa página contém. Para extract, é o seu esquema e qualquer texto que você fornecer diretamente.

Seu token de API vai para MCP_URL como um token de portador e para nenhum outro lugar. Este pacote nunca o grava em disco.

O que os grupos de navegador armazenam. browser e browser_full controlam um navegador no servidor, e browser_save_session mantém deliberadamente os cookies desse navegador no lado do servidor para que uma execução posterior possa pular o login. Esse é o recurso, e também é a parte em que é preciso pensar mais: uma sessão salva é uma credencial ativa para esse site, mantida por nós. browser_list_sessions mostra o que existe. Ambos os grupos são opcionais e desativados por padrão.

As ferramentas de CAPTCHA do lado da página — detect_captcha e solve_captcha_on_page, ambas ativadas por padrão — existem em parte para evitar isso. Elas leem o HTML do seu navegador e devolvem o JavaScript ou cookie para aplicar na sua sessão, então a sessão nunca se move.

O que permanece na sua máquina. Um arquivo: o cache offline da lista de ferramentas — nomes de ferramentas e esquemas JSON, indexados por endpoint, em CACHE_DIR (padrão ~/Library/Caches/2captcha-mcp no macOS, $XDG_CACHE_HOME/2captcha-mcp no Linux, %LOCALAPPDATA%\2captcha-mcp no Windows). Sem argumentos, sem resultados, sem credenciais. Excluí-lo custa uma ida e volta na próxima inicialização.

Retenção e remoção. Os dados de solicitação são retidos no lado do servidor conforme a política de privacidade da 2Captcha. Para descartar uma sessão de navegador armazenada, carregue-a e limpe-a, ou entre em contato com support@2captcha.com. Para remover tudo localmente, exclua o diretório de cache; para invalidar o acesso, gire sua chave em 2captcha.com/setting.

Como funciona

Este pacote é uma ponte stdio leve para o serviço remoto: os esquemas de ferramentas são buscados ao vivo do servidor e mantidos por 60 segundos, para que o pacote nunca se desvie da superfície de ferramentas implantada, e novas ferramentas do lado do servidor apareçam automaticamente sob GROUPS=all. As chamadas são encaminhadas literalmente — incluindo structuredContent, imagens (capturas de tela) e erros de ferramenta — com reconexão automática se a conexão cair no meio da sessão, e novas tentativas com backoff exponencial em respostas 429 e 5xx, respeitando Retry-After.

Ele inicia mesmo que a rede não inicie. A lista de ferramentas é armazenada em cache no disco, então um laptop que acorda com Wi-Fi morto ainda registra um servidor funcional e repopula suas ferramentas por notificação assim que a conexão volta — em vez de o cliente marcar o servidor como quebrado até você reiniciá-lo manualmente. A única falha na qual ele ainda se recusa a iniciar é um token rejeitado, porque essa não se resolve sozinha.

Os custos são medidos no lado do servidor contra seu token: scraping gasta recursos de proxy/navegador, solve_captcha gasta uma solução por chamada, e a extração de LLM em parse_marketplace/extract cobra sua própria chave de LLM quando você tem uma guardada (BYOK), ou o padrão do servidor caso contrário. Passe include_meta: true para as ferramentas de análise para ver exatamente o que uma chamada gastou — este serviço é o único que relata o preço de uma chamada ao agente que a faz, em vez de apenas em um painel depois.

A permissão do nível gratuito usa esse mesmo medidor, vinculado à sua conta em sua própria janela de 30 dias — é por isso que get_account pode dizer exatamente quantas chamadas e quanto de gasto você ainda tem.

Solução de problemas

"Cannot run without the API_TOKEN env"

Defina API_TOKEN no bloco env da configuração do seu cliente para sua chave de API da 2Captcha (https://2captcha.com/setting). A permissão gratuita é medida por conta, então ela precisa da credencial — criar uma conta é gratuito.

"Authentication to … failed"

O servidor rejeitou o token. Verifique se há espaços em branco e confirme qual credencial sua implantação aceita (chave de API da 2Captcha vs. um token emitido pelo operador).

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

A permissão mensal da sua conta foi gasta. A janela é contínua, então a capacidade retorna conforme chamadas mais antigas expiram; get_account mostra quanto resta e quando. Em um servidor auto-hospedado, o operador aumenta WEBPARSE_FREE_TIER_MAX_CALLS / WEBPARSE_FREE_TIER_MAX_SPEND_USD, ou isenta a conta completamente.

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

O operador restringiu a permissão a um subconjunto de ferramentas (WEBPARSE_FREE_TIER_TOOLS). Isso é uma restrição de todo o servidor, não algo que uma credencial diferente resolva — peça a eles para ampliá-la. get_account lista as ferramentas que sua conta pode acessar.

"spawn npx ENOENT"

Seu cliente MCP não consegue encontrar o Node. Instale Node.js ≥ 18 e certifique-se de que npx esteja no PATH que o cliente usa (em aplicativos GUI do macOS, use um caminho absoluto para npx).

Timeouts em sites difíceis

Páginas que forçam a escada completa (navegador gerenciado + solução de CAPTCHA) podem levar minutos. Aumente POLLING_TIMEOUT (segundos) e prefira scrape_pages/parse_pages para muitas URLs, para que a espera aconteça no lado do servidor.

Uma ferramenta que espero está ausente

O padrão expõe parsing,batch,captcha. Para uma ferramenta de navegador, defina GROUPS=browser (as 11 ferramentas de login) ou GROUPS=browser_full (todas as 23); GROUPS=all desativa a filtragem completamente. Se ainda estiver ausente, o próprio servidor tem esse conjunto de ferramentas desativado — ou o operador restringiu a permissão a um subconjunto de ferramentas (get_account dirá).

Licença

MIT — © 2Captcha. Veja LICENSE.