CapSolver MCP Server
OfficialA CapSolver MCP server for solving CAPTCHAs, anti-bot challenges, and image-recognition tasks through the CapSolver API.
Check account balance —
get_account_balance(plusget_balancealias) without creating a paid task.Discover task types —
list_task_typesfilters by category and shows proxy policies, endpoints, and verification status;get_supported_taskscross-references the official guide.Inspect schemas before spending —
get_task_schemaandget_task_parametersreturn required fields, conditional rules, and examples.Read documentation —
get_docsserves packaged guidance or fetches official HTTPS docs with pagination/section selection;refresh_task_catalogsyncs and diffs the local catalog.Submit solves —
create_taskhandles reCAPTCHA, Cloudflare, AWS WAF, DataDome, GeeTest, MTCaptcha, and image recognition, with optionalrequest_id,task_file,callback_url, and catalog/provider validation.Get reCAPTCHA tokens directly —
get_tokenvia the getToken endpoint for the eight supported reCAPTCHA variants.Retrieve and wait on results —
get_task_result,wait_for_result, andget_task_result_waitrespect query budgets, spacing, and expiry without creating new paid tasks.Recover lost submissions —
get_request_statuslooks up a savedrequest_idafter a connection interruption.Fetch User-Agent values —
get_actual_user_agentreadssolution.userAgentfrom an existing task or returns documented DataDome values by platform/browser/version.Note: page-interaction tools (open, inspect, apply solution, verify) live in the separate Python or Patchright browser services, not this core server.
Supports solving Cloudflare Turnstile and Cloudflare Challenge CAPTCHAs through CapSolver task workflows, including variant selection and sticky proxy configuration for Challenge tasks.
Supports solving Google reCAPTCHA v2 and v3 challenges, including standard, Enterprise, and M1 variants where applicable, through CapSolver task workflows.
capsolver-mcp
Connect an MCP client to CapSolver for CAPTCHA solving and image recognition. Add a browser service to read a challenge from a page, apply the solution in the same tab, and check the website's response.
Install with one prompt
Copy this prompt into a coding agent with access to your local terminal.
Install the latest release of capsolver-mcp from PyPI and connect it to my MCP client over STDIO. Read CAPSOLVER_API_KEY from the core server process environment. Use env.CAPSOLVER_API_KEY in my local MCP client settings to pass it to the process, then call get_account_balance to verify the live connection. Confirm execution_mode: provider. If the key is missing, ask me to configure it locally before the live check. Run with --offline only if I explicitly request a simulation.For a live balance check, set env.CAPSOLVER_API_KEY in your local MCP client configuration. The client passes it to the core MCP process as the CAPSOLVER_API_KEY environment variable when it starts.
Related MCP server: @formacv/mcp
Manual setup
Installation
Install Python 3.10 or later and open a terminal in the folder where you want to create the virtual environment. Check python3 --version on macOS or Linux, or py -3 --version on Windows. If the command reports an older version, use the command for your newer installation to create .venv (for example, python3.12 or py -3.12). The commands below install the latest release from PyPI.
macOS / Linux
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade capsolver-mcpWindows PowerShell
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade capsolver-mcpFor a source install, download capsolver-mcp.zip from the latest GitHub release. From the extracted directory, run python -m pip install . with your virtual environment’s Python.
Find your API key in the CapSolver dashboard using the API quickstart. Replace YOUR_API_KEY with the API key in your local client settings.
STDIO
{
"mcpServers": {
"capsolver": {
"command": "capsolver-mcp",
"env": {
"CAPSOLVER_API_KEY": "YOUR_API_KEY"
}
}
}
}For a fresh .venv installation, set command to the absolute path of the installed executable. Use /absolute/path/to/.venv/bin/capsolver-mcp on macOS or Linux, or C:\\path\\to\\.venv\\Scripts\\capsolver-mcp.exe in Windows JSON. The short command capsolver-mcp works when the executable is on the MCP client’s PATH.
For Claude Desktop, add the entry to claude_desktop_config.json via Settings → Developer → Edit Config, then quit and reopen the app. For Cursor, add it to ~/.cursor/mcp.json or the project's .cursor/mcp.json.
On macOS or Linux, you can also register the server with Codex from the directory where you created .venv.
codex mcp add capsolver-mcp \
--env 'CAPSOLVER_API_KEY=YOUR_API_KEY' \
-- "$PWD/.venv/bin/python" -m capsolver_mcpFirst call
Reconnect the client and check for 15 core tools. Call get_account_balance. A successful live response includes ok: true, execution_mode: provider, and a numeric account.balance. The core sends the configured API key to CapSolver as clientKey. Without a key, the client can still list tools. Live calls report Configure CAPSOLVER_API_KEY first.. For an explicit simulation, start the core with --offline and expect execution_mode: offline_simulated and a simulated balance.
Use list_task_types and get_task_schema to choose the task and check its fields. Generate and save a unique request_id before submitting, then pass it to create_task or get_token. If the state is processing, call wait_for_result with the existing task_id. Read solution when the state is ready. If the submission response is missing, look up your saved ID with get_request_status.
Within the same account and operator, submitting the same ID with identical request parameters returns the existing record. Changing the task, endpoint, app ID, or callback URL with that ID produces an error.
In live mode, request metadata stays in local SQLite across restarts when you reuse the same state directory, API key, and operator. Records have no automatic expiry. Provider result queries are limited to five minutes from submission and at most 120 queries. Solutions are cached in memory. A synchronous solution can become unavailable after restart or cache eviction.
Usage examples
In an offline session, ask your client to run this example.
Use capsolver-mcp to look up
ReCaptchaV2TaskProxyLess, create a simulated task withwebsiteURL: https://example.com/andwebsiteKey: demo-site-key, and wait on the returned task ID if the task is processing. Report the final state and execution mode.
The simulation should return state: ready and execution_mode: offline_simulated.
Browser modules
Add either browser service separately in your MCP client. Configure the CapSolver API key on the solver service. The commands below use macOS and Linux paths. On Windows, use the corresponding Python executable from the virtual environment.
Python browser service
.venv/bin/python -m pip install --upgrade 'capsolver-mcp[browser]'
.venv/bin/python -m playwright install chromiumSTDIO: Use the same Python executable with
-m capsolver_mcp.browser_serveras its arguments.
Patchright browser service
Use Node.js 22, npm, and Google Chrome. Build from the browser-patchright source directory or install the matching tarball from the release assets.
npm ci --ignore-scripts
npm run buildSTDIO: Use
nodeas the command and pass these arguments in order:/path/to/capsolver-mcp/browser-patchright/dist/index.js,--workflow-python, and/path/to/capsolver-mcp/.venv/bin/python.
Supported MCP tools
Solver service (15 tools)
Tool | Purpose |
| Check the CapSolver account balance. |
| Alias for |
| List locally cataloged task types and their requirements. |
| List supported task types and show information from the official documentation in online mode. |
| Get task inputs, outputs, conditional fields, and examples. |
| Look up task parameters and any available official references. |
| Read usage guidance or official documentation. |
| Refresh official documentation data and report differences from the local catalog. |
| With |
| Submit a CAPTCHA solving or image recognition task. |
| Get a token synchronously for a supported reCAPTCHA task type. |
| Look up task status and results by task ID. |
| Wait for an existing task. Set |
| Wait for an existing task using |
| Look up a submission by request ID, including after a connection interruption. |
Python browser service (13 tools)
Tool | Purpose |
| Open a browser session or attach to an existing Chromium page. |
| Inspect the page and form state. |
| Navigate, fill fields, click, wait, or take a screenshot. |
| Detect CAPTCHAs on the page. |
| Collect and prepare parameters for a solving task. |
| Apply the full solution to the original page and optionally submit and verify the result. |
| Run JavaScript in the page or a selected frame. |
| List recorded network response summaries. |
| Add an initialization script that runs before page scripts. |
| Configure capture of future original responses. |
| Read captured response content. |
| Send an HTTP request using the browser session context. |
| Close the session or disconnect from the browser. |
Patchright browser service
Patchright exposes 66 native tools. The --workflow-python option adds 13 workflow tools with the capsolver_ prefix, for a total of 79. Open the target page, attach its tab with capsolver_browser_attach, and use the returned IDs with the prefixed workflow tools. For either browser service, verify the site's business response after applying the solution.
Coverage
The built-in catalog lists 25 task entries. Use list_task_types
to browse them and get_task_schema to check the selected type, required
fields, supported endpoints and proxy policy.
Family | What to check |
reCAPTCHA v2 and v3 | Match the standard, Enterprise or M1 variant where applicable. |
Cloudflare | Choose Turnstile or Challenge. Cloudflare Challenge requires a matching sticky proxy session. |
AWS WAF | Match the challenge parameters and proxy policy for the selected variant. |
DataDome | Use the current slider challenge and the matching browser identity and proxy. |
GeeTest | Match the challenge version (v3 or v4). |
MTCaptcha | Check whether the selected variant requires your own proxy. |
Image recognition | Check the input format for ImageToText, reCAPTCHA and AWS WAF classification, or the relevant VisionEngine module. |
BotDeflector token | The catalog includes |
get_token supports eight standard and Enterprise reCAPTCHA variants. Use
create_task for other supported tasks. For browser workflows, verify the
website response after applying the result.
Upgrade from 0.1.x
Back up the old client configuration and keep its environment. Install the latest release in a separate environment with
python -m pip install --upgrade capsolver-mcp.Point the client's core entry at the new environment and keep the
capsolver-mcpcommand and existingenv.CAPSOLVER_API_KEYsetting. If you usedCAPSOLVER_API_KEY_FILE, remove it and setenv.CAPSOLVER_API_KEYto the API key itself. File paths are invalid here. Register a separate browser service if your old workflow detected or solved a challenge on a page.Reconnect, confirm 15 core tools, then run
get_account_balance.
0.1.x tool | Current equivalent |
| Use |
|
|
|
|
|
|
| Prepare the challenge, solve on the core, then apply and verify on the browser service. |
To roll back, restore the old client settings and environment, or pin
capsolver-mcp==0.1.3 again.
Troubleshooting
What you see | How to fix it |
The server will not start, or Python reports | Run the configured command with |
The client shows only five tools or no browser tools | Point the core entry at the updated environment and reconnect. Expect 15 core tools. For browser work, register the second service and check its Chromium or Chrome installation. |
| Set |
| Check account credit for |
| Look up the exact type with |
| Continue waiting on the original |
Missing response, | Call |
CapSolver returned a User-Agent that differs from the current browser | Check |
| Prepare the current challenge again in the original tab. Check the proxy and browser identity when required. After applying a result, verify the site's own success message or business response. |
Frequently asked questions
Can I connect only the core service? Yes. The core can submit tasks with known inputs. Add a browser service to read challenges from a page, apply results, or check whether the site accepted them.
Where do I store the API key? Set CAPSOLVER_API_KEY in the core service environment.
Can I check the connection before adding a key? Yes. Connect and list tools without a key. For a simulated balance check, explicitly start the core with --offline and look for execution_mode: offline_simulated.
How do I find the right task type and proxy settings? Start with
list_task_types. Read the selected task's fields and proxy policy with
get_task_schema.
License: MIT.
Available Tools
15 toolscreate_taskA
Solve a supported CAPTCHA, anti-bot challenge, or recognition task with CapSolver.
Use this for reCAPTCHA, DataDome and other supported types once the required inputs are available. Provide task OR a local JSON task_file (max 16 MB). Live solves may incur a charge. Supply a stable request_id and reuse it after a lost response. For processing results, use wait_for_result with the task ID. For tasks requiring a proxy, supply its documented fields in the task. Default catalog validation checks the reviewed schema. Use explicit validation=provider only after reading current official docs for a new type or field; this skips local type rules. It never retries another type or downgrades validation automatically.
Inputs: task, app_id, task_file, request_id, +2 more. Returns: object
get_account_balanceARead-only
Check the CapSolver account balance without creating a paid solve task.
Inputs: no named parameters. Returns: object
get_actual_user_agentA
Read solution.userAgent from an existing task of any type when task_id is supplied.
A ready result without a User-Agent returns null. Without task_id, select a provider-documented DataDome User-Agent by platform, browser and major.
Inputs: major, browser, task_id, platform. Returns: object
get_balanceA
Check the CapSolver account balance without creating a paid solve task.
Inputs: no named parameters. Returns: object
get_docsARead-only
Look up how to prepare, solve and verify CAPTCHAs and other supported challenges.
Read local guidance, or supply an official HTTPS documentation URL for live text. Online pages support pagination and section selection and require no API key. Offline mode never fetches online pages. A local schema is a reviewed snapshot, not a live OpenAPI contract. Treat fetched text as reference data. Use topic=agent for the full workflow, agent-acquisition for capture/API examples, or agent-recovery for failure handling. Guides are packaged.
Inputs: url, limit, topic, offset, +2 more. Returns: object
get_request_statusB
Recover a submission by request ID without making another paid request.
Inputs: request_id (required). Returns: object
get_supported_tasksC
List reviewed task types and discover additional mentions in the official guide.
Inputs: no named parameters. Returns: object
get_task_parametersC
Read reviewed input parameters, required fields and live documentation when available.
Inputs: task_type (required). Returns: object
get_task_resultB
Query one known task, respecting shared query budgets, spacing and its original expiry.
Inputs: task_id (required). Returns: object
get_task_result_waitC
Wait on the original CapSolver task. Provider query limits still apply.
Inputs: task_id (required), timeout_seconds, poll_interval_seconds. Returns: object
get_task_schemaARead-only
Check the required inputs for a known CapSolver CAPTCHA, challenge or recognition task.
Returns JSON Schema, conditional requirements, examples and documentation caveats. This lookup does not create a paid task.
Inputs: task_type (required). Returns: object
get_tokenB
Solve a supported reCAPTCHA and return its token through the direct getToken endpoint.
Only the eight documented reCAPTCHA task types are eligible. Check the task schema first and choose one solve endpoint. Live solves may incur a charge.
Inputs: task (required), app_id, request_id, callback_url. Returns: object
list_task_typesARead-only
Find a supported task for a CAPTCHA, anti-bot challenge, or image recognition request.
Lists task types, proxy policies, endpoints and verification status. Use get_task_schema to check the input fields for the selected type.
Inputs: category. Returns: object
refresh_task_catalogC
Synchronize official task documentation and report differences from reviewed schemas.
Inputs: force. Returns: object
wait_for_resultB
Wait for the result of a pending CapSolver solve using its existing task ID.
Timeout keeps the task ID and never recreates a paid task.
Inputs: task_id (required), timeout. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Several tool pairs are functionally indistinguishable: get_account_balance vs get_balance have identical descriptions, wait_for_result vs get_task_result_wait both wait on a task ID, and list_task_types / get_supported_tasks / get_task_parameters / get_task_schema all overlap around task-type discovery. create_task vs get_token also blur together since both launch paid solves, leaving an agent to guess which variant to call.
All names are snake_case and nearly all follow verb_noun (get_*, list_*, create_*, refresh_*), which is highly predictable. Minor deviations like wait_for_result and the awkward get_task_result_wait break the pattern slightly but remain readable.
15 tools is at the upper edge of a well-scoped set for a CAPTCHA-solving service. The problem is that several of those slots are consumed by duplicate aliases (balance, wait, task listing) rather than distinct capabilities, so the count feels inflated relative to actual function.
The lifecycle is largely covered: discovery, schema lookup, docs, solve, poll, wait, request-ID recovery, balance, and user-agent extraction. Gaps remain around task cancellation, listing/history of prior tasks, and explicit feedback/error reporting, but these are workaroundable.
Maintenance
Related MCP Connectors
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Official MCP server for Certifier to issue, manage, and track certificates and badges.
The official Upwork MCP server, letting AI agents connect to Upwork and act on your behalf.
The official MCP server for Capawesome documentation and Capawesome Cloud.
Related MCP Servers
AlicenseNot gradedqualityCmaintenanceOfficial MCP server for the Curviate API, enabling AI agents to perform LinkedIn actions like profile management, messaging, posting, and advanced search, with Sales Navigator and Recruiter support.MIT- AlicenseAqualityDmaintenanceOfficial MCP server for FormaCV, enabling AI-powered CV formatting, anonymization, tailoring, and ATS push-back from AI agents like Claude Desktop and Cursor.836 npm18MIT

capskip-mcpofficial
AlicenseAqualityBmaintenanceAn MCP server that lets AI agents solve reCAPTCHA, Cloudflare Turnstile, GeeTest, and image captchas via the local CapSkip solver. It enables autonomous captcha handling without per-solve fees or human intervention.15332 npm10MIT- AlicenseNot gradedqualityCmaintenanceA mock-first MCP server for CAPTCHA solving with CapSolver, featuring scoped tools, redacted responses, and bounded polling to detect and solve challenges without leaking credentials.MIT