2Captcha MCP README

2Captcha MCP: tools for AI agents, web scraping and browser automation

Web scraping with anti-bot bypass, marketplace parsing to structured JSON, and CAPTCHA solving for AI agents over the Model Context Protocol.

Works with Claude, Cursor, coding agents, and any MCP-compatible client.

Free monthly allowance on every account — sign up, add your API key, and the first 200 calls a month are on us. What's included

Free Tier • Quick Start • Install • Tool Groups • Tools • Configuration • Troubleshooting

English • Русский

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

_{Codex desktop, same model and prompt, recorded one after the other · 3× speed}

[!IMPORTANT] The official 2Captcha MCP package is @2captcha/mcp (published under the @2captcha npm organization). The unscoped 2captcha-mcp package on npm is not affiliated with 2Captcha — don't put your API key into it.

Overview

The 2Captcha MCP server gives AI agents real-time access to web data that blocks ordinary HTTP clients. It exposes 40 tools covering:

• Web search — ranked organic results (title, URL, snippet) for a query
• Page scraping — any URL as clean Markdown or raw HTML. Every request runs through a tiered anti-bot ladder: hidden JSON APIs, a TLS-impersonating HTTP client, rotating residential proxies, and a managed browser with CAPTCHA solving — escalating only as far as the page requires, so easy pages stay fast and cheap.
• Marketplace parsing — product pages and search listings as structured JSON (title, price, rating, seller, stock, offers). Deterministic tiers first (hidden marketplace APIs, JSON-LD, learned selectors); an LLM extraction pass only when they miss.
• Structured extraction — any URL or raw text plus your own JSON Schema in, matching JSON out.
• Batch jobs — run the scraping/parsing tools over many URLs as a background job: submit, poll, cancel.
• CAPTCHA solving, including in your browser — solve any type 2Captcha supports (reCAPTCHA, Turnstile, hCaptcha, DataDome, images, …). detect_captcha names the wall on a page you are already driving in Playwright MCP, browser-use or an extension — free, from HTML you paste in — and solve_captcha_on_page solves it and hands back the exact JavaScript or cookie to apply in your own session. Nothing has to move to our browser.
• Browser logins — opt-in. Sign in to a site whose login form is behind a CAPTCHA, in a managed browser, and save the session for later.

Two deployment options: the hosted remote server (one URL, no installation) or a local instance via npx @2captcha/mcp.

Free tier: what's included

Signing up for 2Captcha is free, and an account comes with a monthly allowance on this server: 200 calls or $0.50 of measured spend per 30 days, whichever comes first, across the whole tool surface — scraping, marketplace parsing, structured extraction, batch jobs, the browser tools and CAPTCHA solving. No card, no separate plan, no feature gating.

The window is rolling rather than calendar-monthly, so capacity returns continuously instead of everyone's quota resetting on the 1st.

The allowance is metered per account, which is why a credential is required: the identity is what it is counted against. There is no anonymous mode — an IP address is not an identity, and a free tier keyed to one is a free tier keyed to a proxy pool.

get_account reports what is left, so an agent can plan around the limit instead of discovering it as a failure halfway through a task:

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

Nothing else on this server bills per call: CAPTCHA solves are charged to your 2Captcha balance as they always were, and include_meta: true reports what any call actually cost. So when the allowance runs out, calls are refused until the window refills — the message says so, and says the operator can raise it. Need more than the allowance? Talk to the operator; on the hosted service that is 2Captcha support.

Quick Start

Hosted server — no installation

Add the URL to your MCP client with an Authorization header:

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

Your token is your 2Captcha API key (account settings) or the bearer token your server operator issued. Signing up is free and brings the monthly allowance with it.

Local server via npx

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

The local server mirrors the hosted tool surface over stdio — use it with clients that can't send auth headers or only launch local MCP servers.

Install

Every client below needs the same two things: the command npx @2captcha/mcp with API_TOKEN in its environment, or — where the client speaks HTTP — the hosted URL plus an Authorization: Bearer header. Get a token at 2captcha.com/setting; signing up is free and brings the monthly allowance with it.

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

Try it

Ask your agent:

Parse https://www.wildberries.ru/catalog/0/search.aspx?search=coffee as search results and list the five cheapest items.

Scrape https://news.ycombinator.com and summarize the top stories.

What's my 2Captcha balance?

Tool Selection: Groups

By default the server exposes the parsing, batch, and captcha groups (17 tools). The browser groups are opt-in: they are the one part of the surface that costs a client real context every turn, and most tasks never touch it.

Measured cost of each group, as the tool definitions a client puts on every request (name + description + JSON Schema, tiktoken o200k_base — regenerate with the service repo's benchmarks/scripts/tool_surface_tokens.py):

Why captcha is a default and browser is not. detect_captcha and solve_captcha_on_page work on HTML from whatever browser you are already driving, so they are useful to a client that never opens ours — which is the common case. See Driving your own browser.

Configuration examples

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

Individual tools, no groups:

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

GROUPS and TOOLS combine (union). Tool availability is ultimately the server's decision — a group named here only filters what the server actually advertises.

Tools Reference (40 Tools)

Which tool to use

• Looking for pages to scrape? → search_web (query → ranked URLs)
• Just need the page content? → scrape_page (no LLM, cheapest)
• Need a URL inventory before batching? → discover_urls (robots.txt + sitemaps, no crawling)
• Building a search URL for a site? → discover_search_params (its real parameter names, not a guess)
• Product or search page → JSON? → parse_marketplace (deterministic tiers first, LLM fallback)
• Your own schema from any page/text? → extract (always one LLM call, or cache)
• Many URLs? → scrape_pages / parse_pages + get_job
• Hit a CAPTCHA in your own browser? → detect_captcha (free) then solve_captcha_on_page
• A CAPTCHA token for your own automation? → list_captcha_types then solve_captcha
• Log in past a CAPTCHA and keep the session? → GROUPS=browser, then browser_navigate → browser_fill → browser_click → browser_save_session

Parsing

Batch jobs

Driving your own browser (recommended)

If you already have a browser — Playwright MCP, browser-use, a Chrome extension, your own Playwright script — keep it, and use these two tools for the part that needs a solver account:

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 is a complete expression with the token already inlined — it is the same injector this service's own render tier uses — so it drops straight into page.evaluate, a devtools console, or any run-JS tool. When the answer is a cookie instead (DataDome, AWS WAF) you get the parsed cookie and the instruction to re-request rather than reload.

Two things worth knowing. Pass html from your browser, because anti-bot walls are raised per client and our address sees a different page than yours. And for DataDome or CaptchaFox pass your own proxy and user_agent: those answers are minted for the identity that solved them, so one solved as us is refused in your session even though it is technically correct.

Browser logins (GROUPS=browser, 11 tools)

The managed browser is not trying to out-Playwright Playwright. That surface is free and you probably already have it, and this one holds one live page per account, so it is the wrong tool for anything parallel. What it has that a plain browser does not is that it solves the CAPTCHA in the login form, and it can keep the cookies afterwards — so the group is scoped to exactly that, at 2,842 tokens instead of 5,201:

Set GROUPS=browser_full for the complete 23-tool surface — adding history (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 and browser_save_as_pdf.

CAPTCHA

Local

Configuration

Environment variables

MAX_SPEND_USD is the one worth setting if you set only one. A call limit bounds the wrong quantity — a single parse_pages over 500 URLs costs more than a hundred scrape_page calls — so RATE_LIMIT protects you from a runaway loop while MAX_SPEND_USD protects you from a runaway bill. A call's cost is only known once the server answers, so the cap is checked against what has already been spent: it bounds the overshoot to one call rather than pretending to be exact.

Command line

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

What leaves your machine

Worth settling before this reaches a security review, because the honest answer is "more than a local tool, less than a browser extension".

Where it goes. One place: MCP_URL — https://mcp.2captcha.com/mcp unless you point it at your own server. No telemetry, no analytics, no third party. The bridge opens no listening port.

What travels with a tool call. That tool's arguments, forwarded verbatim and neither inspected nor logged by the bridge. For scrape_page that is a URL. For detect_captcha and solve_captcha_on_page it is the page HTML you pass in — and HTML taken from a signed-in session contains whatever that page contains. For extract it is your schema and any text you supply directly.

Your API token goes to MCP_URL as a bearer token and nowhere else. This package never writes it to disk.

What the browser groups store. browser and browser_full drive a browser on the server, and browser_save_session deliberately keeps that browser's cookies server-side so a later run can skip the login. That is the feature, and it is also the part to think hardest about: a saved session is a live credential for that site, held by us. browser_list_sessions shows what exists. Both groups are opt-in and off by default.

The page-side CAPTCHA tools — detect_captcha and solve_captcha_on_page, both on by default — exist partly to avoid this. They read HTML from your browser and hand back the JavaScript or cookie to apply in your session, so the session never moves.

What stays on your machine. One file: the offline tool-list cache — tool names and JSON schemas, keyed by endpoint, under CACHE_DIR (default ~/Library/Caches/2captcha-mcp on macOS, $XDG_CACHE_HOME/2captcha-mcp on Linux, %LOCALAPPDATA%\2captcha-mcp on Windows). No arguments, no results, no credentials. Deleting it costs one round trip on the next start.

Retention and removal. Request data is retained server-side per the 2Captcha privacy policy. To drop a stored browser session, load it and clear it, or ask support@2captcha.com. To remove everything local, delete the cache directory; to invalidate access, rotate your key at 2captcha.com/setting.

How it works

This package is a thin stdio bridge to the remote service: tool schemas are fetched live from the server and held for 60 seconds, so the package never drifts from the deployed tool surface, and new server-side tools appear automatically under GROUPS=all. Calls are forwarded verbatim — including structuredContent, images (screenshots), and tool errors — with automatic reconnection if the connection drops mid-session, and retries with exponential backoff on 429 and 5xx responses, honouring Retry-After.

It starts whether or not the network does. The tool list is cached on disk, so a laptop that wakes on a dead Wi-Fi still registers a working server and repopulates its tools by notification once the connection comes back — instead of the client marking the server broken until you restart it by hand. The one failure it still refuses to start on is a rejected token, because that one will not fix itself.

Costs are metered server-side against your token: scraping spends proxy/browser resources, solve_captcha spends one solve per call, and the LLM extraction in parse_marketplace/extract bills your own LLM key when you have one vaulted (BYOK), the server default otherwise. Pass include_meta: true to the parsing tools to see exactly what a call spent — this service is the only one that reports the price of a call to the agent making it, rather than only in a dashboard afterwards.

The free-tier allowance runs on that same meter, keyed to your account over its own 30-day window — which is why get_account can tell you exactly how many calls and how much spend you have left.

Troubleshooting

"Cannot run without the API_TOKEN env"

Set API_TOKEN in the env block of your client config to your 2Captcha API key (account settings). The free allowance is metered per account, so it needs the credential — signing up is free.

"Authentication to … failed"

The server rejected the token. Check for whitespace, and confirm which credential your deployment accepts (2Captcha API key vs. an operator-issued token).

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

Your account's monthly allowance is spent. The window is rolling, so capacity returns as older calls age out; get_account shows how much is left and when. On a self-hosted server the operator raises WEBPARSE_FREE_TIER_MAX_CALLS / WEBPARSE_FREE_TIER_MAX_SPEND_USD, or exempts the account entirely.

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

The operator narrowed the allowance to a subset of tools (WEBPARSE_FREE_TIER_TOOLS). That is a server-wide restriction, not something a different credential lifts — ask them to widen it. get_account lists the tools your account can reach.

"spawn npx ENOENT"

Your MCP client can't find Node. Install Node.js ≥ 18 and make sure npx is on the PATH the client uses (on macOS GUI apps, use an absolute path to npx).

Timeouts on hard sites

Pages that force the full ladder (managed browser + CAPTCHA solve) can take minutes. Raise POLLING_TIMEOUT (seconds), and prefer scrape_pages/parse_pages for many URLs so the waiting happens server-side.

A tool I expect is missing

The default exposes parsing,batch,captcha. For a browser tool, set GROUPS=browser (the 11 login tools) or GROUPS=browser_full (all 23); GROUPS=all disables filtering entirely. If it is still missing, the server itself has that tool set disabled — or the operator narrowed the allowance to a subset of tools (get_account will say).

License

MIT — © 2Captcha. See LICENSE.