2Captcha MCP server

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"

Or locally:

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

One click: download 2captcha-mcp-<version>.mcpb from the latest release and open it. Claude Desktop installs it as an extension and asks for your API token — no Node, no npx, no config file.

Or by hand: edit the config file (macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json) and restart the app:

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

Add to ~/.cursor/mcp.json:

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

Or add it to ~/.codex/config.toml by hand:

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

Add to .vscode/mcp.json:

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

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

Or connect the Inspector directly to https://mcp.2captcha.com/mcp (transport Streamable HTTP, header Authorization: Bearer YOUR_API_TOKEN).

Add to ~/.codeium/windsurf/mcp_config.json:

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

Add to Zed's settings.json (cmd/ctrl + ,):

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

Settings → AI → Manage MCP servers → + Add, then paste:

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

Add to ~/.gemini/settings.json:

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

Add to ~/.kimi-code/mcp.json, or .kimi-code/mcp.json for a single project:

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

Or skip the local process — a url key instead of command makes it an HTTP server:

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

/mcp-config in the TUI edits the same file; /mcp shows connection status.

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

Or hosted:

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

Both write to ~/.qwen/settings.json (.qwen/settings.json for project scope), which you can edit by hand — note the HTTP field is httpUrl, not url:

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

dsh reaches MCP servers through the @deepseek-ai/dsh-mcp-client plugin — one entry per server in cordis.patch.yml, or any file you pass to --patch:

- 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

Or against the hosted server:

- 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}`'

The agent then sees the tools as mcp__2captcha__<tool>.

Two surfaces, two answers.

Through a coding CLI. The GLM Coding Plan exposes an Anthropic-shaped endpoint, so Claude Code runs on GLM and keeps its own MCP config. Set ANTHROPIC_BASE_URL to https://api.z.ai/api/anthropic and ANTHROPIC_AUTH_TOKEN to your Z.ai key in ~/.claude/settings.json, then install this server exactly as in the Claude Code block above.

Through the API. Z.ai's chat/completions calls remote MCP servers itself. There is no local process in that path, so it needs the hosted URL:

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

Streamable HTTP is the default transport, so transport_type can be left off. allowed_tools trims what the model sees; so does GROUPS — see Tool Selection.

MiniMax publishes MCP servers (speech, image, video) but no first-party MCP client, so there is no MiniMax-specific file to edit for this server. Two routes that work today:

• Run a MiniMax model inside any client above that lets you pick the backend — Cline, Continue, Cursor and LM Studio all do — and install 2captcha there as usual.
• For hosts that accept a remote MCP URL directly, point them at https://mcp.2captcha.com/mcp with an Authorization: Bearer YOUR_API_TOKEN header.

Add to ~/.continue/config.yaml:

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

Program → Install → Edit mcp.json:

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

MCP Servers → Configure → Edit cline_mcp_settings.json:

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

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

Or add it permanently with goose configure → Add Extension → Command-line Extension, command npx @2captcha/mcp, environment variable API_TOKEN.

Use the MCP Client Tool node against the hosted server — no local process to manage:

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

Point it at the parsing tools for scraping workflows; see Tool Selection for trimming the surface the agent sees.

The server is a plain stdio MCP server, so anything that can launch a command works:

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

Clients that speak Streamable HTTP can skip the process entirely and use https://mcp.2captcha.com/mcp with an Authorization: Bearer header.

Published to GHCR on every release, for amd64 and arm64:

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

-i matters: the server speaks MCP over stdin/stdout. In a client config:

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

The image runs as the non-root node user and contains only the bundled server — no package manager, no dependency tree.

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):

Group	Tools	Tokens
parsing	7	3,936
batch	4	1,759
captcha	6	2,180
default (the three above)	17	7,875
browser	11	+2,842
browser_full	23	+5,201
all	40	13,076

Group	Tools	What it's for
parsing	scrape_page, search_web, discover_urls, discover_search_params, parse_marketplace, extract, get_account	Search the web, scrape pages, discover a site's URLs and its search parameters, parse marketplaces, extract structured JSON
batch	scrape_pages, parse_pages, get_job, cancel_job	The parsing tools over many URLs as background jobs
captcha	list_captcha_types, solve_captcha, detect_captcha, solve_captcha_on_page, captcha_report, captcha_balance	Solve any CAPTCHA type 2Captcha supports — including one on a page in your own browser
browser	11 browser_* tools	Sign in behind a CAPTCHA in a managed browser and save the session
browser_full	all 23 browser_* tools	The complete Playwright-style surface, when you actually want it here
all	everything the server advertises	No filtering — includes tools added server-side in the future

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

Tool	Description	Costs money?
scrape_page	Fetch a page and return its readable content as markdown (or raw HTML with clean=false). Options: render, keep_links, structured_data, country, max_chars/offset windowing, per-call freshness_seconds caching.	proxy/browser only
search_web	Find URLs for a query: ranked organic results with title, url and snippet. Options: count, country, engine.	no LLM
discover_urls	List the URLs a site publishes in robots.txt and XML sitemaps — a reviewable inventory for scrape_pages/parse_pages, with pattern/prefix filters. Not a crawler.	no LLM
discover_search_params	A site's real URL search parameters, read off one page: the query parameters its own links use (with values known to work) plus any <form> controls. Use it instead of guessing a search URL.	no LLM
parse_marketplace	Product page (target="product") or listing (target="search_results") → structured JSON. Pass schema for your own shape, include_offers for Amazon Buy-Box data, include_meta for cost/provenance metadata.	LLM only when the deterministic tiers miss
extract	Any URL or raw text + your JSON Schema → extracted JSON. instructions steers the extraction.	always one LLM call (or cache)
get_account	Tenant identity, configured capabilities, session spend counters.	no

Batch jobs

Tool	Description
scrape_pages / parse_pages	The tools above over many URLs; return a job_id immediately (or wait up to wait_seconds).
get_job	Poll status and collect per-item results.
cancel_job	Stop a running job (stops the spending).

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.