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 npm organization). The unscoped package on npm is — don't put your API key into it.
2Captcha MCP server for AI agents with web search, web scraping, browser automation, captcha solving, and scalable web data collection.
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:
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:
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.
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 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:
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:
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.
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):
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.
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)
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.
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.
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
Tool
Description
Costs money?
list_captcha_types
The catalogue of solvable types with their required parameters — call it before solve_captcha instead of guessing.
no
solve_captcha
Solve a CAPTCHA of any supported kind; returns the token/answer, a captcha_id, and the cost.
yes — one solve per call
detect_captcha
Identify the wall on a page — widget type, sitekey, whether a solvable task can be built from it, and the exact solve_captcha call to issue. Pass html from your own browser. Never solves.
no (free with html)
solve_captcha_on_page
Detect + solve in one step, and return an apply block: a self-contained JS expression to evaluate, or a cookie to add and a URL to re-request.
yes — one solve per call
captcha_report
Report a solution good/bad (bad reports refund).
no
captcha_balance
Current balance in USD.
no
Local
Tool
Description
session_stats
Tool usage during this session (calls per tool, rate-limit window). Handled locally, free.
Configuration
Environment variables
Variable
Required
Default
Description
API_TOKEN
yes
—
Your 2Captcha API key, or the bearer token your server operator issued. Signing up is free and includes the monthly allowance
GROUPS
no
parsing,batch,captcha
Comma-separated tool groups (see above): browser adds the 11 login tools, browser_full all 23, all disables filtering
TOOLS
no
—
Comma-separated individual tool names to enable
MCP_URL
no
https://mcp.2captcha.com/mcp
The remote MCP endpoint — set it for a self-hosted server
POLLING_TIMEOUT
no
600
Per-tool-call timeout in seconds (renders, batch jobs and CAPTCHA solves can take minutes)
RATE_LIMIT
no
—
Client-side call limiter, e.g. 100/1h or 50/30m
MAX_SPEND_USD
no
—
Spend cap, measured from what each call reports it cost: 5 for the whole session, or 5/1h for a rolling window
MAX_CONCURRENCY
no
—
Maximum tool calls in flight at once. Without it, an agent fanning out over a URL list opens one connection per URL
CACHE_DIR
no
OS cache dir
Where the offline tool-list cache is kept
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 [email protected]. 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).
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
@2captcha/mcp ต้องใช้ API key ไหม?
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
@2captcha/mcp ใช้ทรานสปอร์ตแบบใด?
@2captcha/mcp ทำงานแบบโลคัลผ่าน stdio
@2captcha/mcp ถูกตรวจสอบล่าสุดเมื่อใด?
ตรวจสอบล่าสุดเมื่อ 2026-11-16 2Captcha MCP server for AI agents with web search, web scraping, browser automation, captcha solving, and scalable web data collection.