Introduction & Quick Start

1. Introducing the CapSolver Python SDK

The SDK ships as three independent packages — each installable on its own via pip install — plus a companion examples repository. Together they let you go from “there’s a CAPTCHA on the page” to “I have a valid token” in just a few lines of Python — whether you’re writing a one-off script, driving a real browser with Playwright, or wiring solving capability into an autonomous AI agent.

It’s powered by CapSolver’s AI solving service. The SDK handles everything on your side — detecting the CAPTCHA, assembling the parameters, calling the service, and filling the result back in — while the actual recognition and solving happens in the cloud. The core idea comes down to a single sentence: your code (or your model) decides what to do, and CapSolver handles solving it.

1.1 Core Features

• ✅ AI-powered token solving — CapSolver returns a token that you submit to the target site.
• ✅ Two usage modes — pure API (Token mode, for known site keys, no browser required) and Playwright-based Browser mode.
• ✅ Coverage of major CAPTCHAs — reCAPTCHA v2 / v3 (including Enterprise) and Cloudflare Turnstile.
• ✅ Fully async API — built on async/await, a natural fit for modern crawlers and agents.
• ✅ Three layered packages — from the low-level engine to agent tools to an MCP service; pick what you need (see 1.2).
• ✅ Bundled CLIs — capsolver, capsolver-agent, and capsolver-mcp let you run diagnostics without writing any code.

1.2 Supported CAPTCHAs & Parameters

The SDK currently solves the following CAPTCHA types:

The core parameters required by every type are website_url + website_key. reCAPTCHA v3 can additionally take page_action, min_score, and an enterprise hint, while Cloudflare can take cdata. You can inspect the types supported by your current build at any time:

cap = create_capsolver(api_key="YOUR_API_KEY")
print(cap.get_supported_captchas())

Note: In Browser mode you don’t need to supply these parameters by hand — get_captcha_info(page) reads the type and site key directly off the live page for you.

2. Core Capabilities (SDK)

2.1 The Three Packages

The full feature set plus one examples repository. These aren’t three peers to choose between — the latter two are both built on top of capsolver-core, simply delivering the same solving capability through a different interface. Pick the one that best matches how you work.

capsolver-core — The Core SDK (Engine)

The lowest-level package, and the shared engine the other two depend on. It breaks solving a CAPTCHA into four steps — detect → read parameters → solve → fill back — and offers two levels of granularity: when the site key is known, go pure API (Token mode, no browser); when you only have the page, let Playwright auto-detect and fill the result back. Fully async, with a pluggable handler registry.

• Best for: scripts, crawlers, and automation where you control the code and don’t need an LLM.
• Entry points: create_capsolver() → solve() / solve_on_page().
• Install: pip install capsolver-core (add [playwright] for Browser mode).

capsolver-agent — Agent Tools

Wraps the core as tools an LLM can call: it provides framework-agnostic tool schemas plus an async executor, as well as ready-made LangChain BaseTool implementations. Within its loop, the model calls “solve” the same way it calls “click” or “type,” and the executor relays that call to the core’s methods and returns a structured result.

• Best for: letting the model decide when to solve — OpenAI function calling, the OpenAI Agents SDK, LangChain, Browser Use, or any custom agent loop.
• Entry points: get_all_tools() + create_executor(), or get_langchain_tools().
• Install: pip install capsolver-agent (add [langchain] for LangChain).

capsolver-mcp — MCP Service

Exposes the same set of tools as a standard service via the Model Context Protocol. Any MCP-compatible client discovers these tools automatically on connection — no per-client adapter code required. Supports three transports: stdio, SSE, and streamable-http.

• Best for: plug-and-play use inside an AI client — Claude Desktop, Claude Code, Cursor, Windsurf, Cline, and more, with almost zero integration code.
• Entry points: the capsolver-mcp command, or create_server().
• Install: pip install capsolver-mcp (add [browser] for the browser tools).

2.2 Use Cases

Any time a CAPTCHA blocks the next step, this SDK earns its place. A few typical scenarios:

Web scraping / data collection

A crawler hits a reCAPTCHA or Turnstile on a listing page, search page, or login wall, and the entire collection pipeline stalls. Use Token mode to get a token and submit it with your request, or use Browser mode to fill it directly into the page — either way, scraping continues. → Recommended: capsolver-core (Token mode when the site key is known; solve_on_page for dynamic pages).

Account & workflow automation

Multi-step flows like sign-up, login, password reset, and checkout often throw a CAPTCHA at one specific step, freezing the whole script. Drop solving into exactly that step — once the token is filled in, the script continues submitting the form, waits for the redirect, and runs the remaining steps to completion. → Recommended: capsolver-core Browser mode; especially smooth when your script already drives Playwright.

AI agents (autonomous browsing)

Give an agent a task like “log in and pull the orders,” and it will hit a CAPTCHA somewhere along the way without warning. Rather than having the model click through itself — pixel-perfect targeting and human-like cursor paths are hard to fake past risk engines, and image-retry loops flood the context window — register a “solve” action for it: when it hits a CAPTCHA, it calls the action, gets a token back, and continues in the same browser session without breaking flow. → Recommended: capsolver-agent (let the model call it itself), or capsolver-mcp (use it directly inside an AI client).

Automated testing / internal tools

End-to-end tests and internal operations tools need to clear CAPTCHA steps on your own or third-party sites reliably, without manual intervention slowing things down. → Recommended: choose by environment — capsolver-core (in code) or capsolver-mcp (in a client).

In short: anywhere you need to clear a CAPTCHA programmatically in Python, this SDK is in range.

3. Installation & API Key Setup

Before you start, keep one thing in mind: the actual solving happens on CapSolver’s cloud service — the SDK only calls it from your side. So the first step isn’t installing a package; it’s having an account and an API key. The setup is three steps, in order: register and get a key → install the SDK → connect the key.

3.1 Register and Get Your API Key

1. Register an account at the CapSolver website.
2. Open the dashboard and copy your API key.
3. Add funds to your account — every successful solve consumes balance, and solving will fail when the balance reaches zero.

3.2 Install the SDK

The three packages are currently hosted as open source on GitHub and are not yet published to PyPI, so install them via git. capsolver-core is the engine, and both capsolver-agent and capsolver-mcp depend on it — so core is always required. Add whichever upper layer you intend to use:

# Engine (required; both other packages depend on it)
pip install git+https://github.com/capsolver-ai/capsolver-core.git
 
# Optional: MCP service — exposes the tools to MCP clients
pip install git+https://github.com/capsolver-ai/capsolver-mcp.git
 
# Optional: Agent tools — LLM-callable tool definitions + LangChain tools
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

For Browser mode (detecting CAPTCHAs on a real page and filling the token back in), add the [playwright] extra and install Chromium:

pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
playwright install chromium

Note: detect and solve_on_page require the browser extra; Token mode needs no browser at all.

The three repositories are:

You can also clone a repository locally before installing — handy for reading the source or doing your own development:

git clone https://github.com/capsolver-ai/capsolver-core.git
cd capsolver-core
pip install .            # or: pip install -e .  for an editable install

3.3 Connect Your API Key

Finally, hand the key from step 3.1 to the SDK. By default, all packages read it from the CAPSOLVER_API_KEY environment variable:

# bash / zsh
export CAPSOLVER_API_KEY="your-capsolver-api-key"
 
# PowerShell
$env:CAPSOLVER_API_KEY = "your-capsolver-api-key"
 
# cmd
set CAPSOLVER_API_KEY=your-capsolver-api-key

Alternatively, skip the environment variable and pass api_key="..." directly to create_capsolver().

4. Your First Solve

With the environment ready, let’s run one end to end with the smallest possible code. Which path you take depends on whether you already know the site key: if you do, use Token mode; if all you have is a page URL, use Browser mode.

4.1 Token Mode (you already know the site key)

When you know the CAPTCHA type, the page URL, and the site key, no browser is needed — hand over the parameters, get a token back.

import asyncio
from capsolver_core import create_capsolver, CaptchaType, CaptchaInfo
 
async def main():
    cap = create_capsolver(api_key="YOUR_API_KEY")
 
    info = CaptchaInfo(
        type=CaptchaType.RECAPTCHA_V2,
        website_url="https://example.com",
        website_key="6Lc...",
    )
    solution = await cap.solve(info)
    print(solution.token)  # submit as g-recaptcha-response
 
asyncio.run(main())

4.2 Browser Mode (one call, straight on the live page)

If all you have is a page — and you’d rather not hunt down the site key yourself — let the SDK auto-detect every CAPTCHA on the page, solve them one by one, and fill the tokens back into the DOM. One call does it all.

import asyncio
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright
 
async def main():
    cap = create_capsolver(api_key="YOUR_API_KEY")
 
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        await page.goto("https://example.com/login")
 
        results = await cap.solve_on_page(page)
        for r in results:
            print(r.info.type, r.solution.token if r.solution else None, r.filled, r.error)
 
asyncio.run(main())