Cursor reCAPTCHA v2 Solver: MCP Setup with CapSolver

TL;DR

• Cursor can call CapSolver through an MCP server, so the agent gets named tools instead of ad hoc CAPTCHA code.
• Token mode fits pages where the reCAPTCHA v2 site key and page URL are already known.
• Browser mode fits Playwright-driven flows where the agent needs detection, solving, and fill-back on the live page.
• Keep API keys outside prompts, allowlist target domains, and stop after bounded retries.
• Use this workflow only for lawful, reasonable, and responsible automation on pages where you have permission.

Introduction

A Cursor reCAPTCHA v2 solver is safest when Cursor calls a narrow MCP tool instead of asking the model to improvise browser steps. CapSolver provides that shape through capsolver-mcp, which exposes solving capabilities as discoverable Model Context Protocol tools. The practical setup is straightforward: install capsolver-core, install capsolver-mcp, add the server to Cursor, and choose token mode or browser mode depending on the workflow. This guide rewrites the common setup into a cleaner developer path with official method names, clear boundaries, and responsible-use checks.

Why Cursor Should Use MCP for reCAPTCHA v2

Cursor works well with MCP because the model can discover named tools and call them with structured arguments. The Model Context Protocol tool model is designed for exactly this pattern: an AI client connects to a tool server, reads available tools, and calls only the tools the server exposes.

For a Cursor reCAPTCHA v2 solver, that means the model does not need to know low-level request polling or hidden form-field behavior. The MCP service owns the operational details, while Cursor decides when a solving tool is appropriate inside an allowed task.

What CapSolver MCP Exposes

CapSolver's MCP service wraps capsolver-core and advertises five tools: solve_captcha, detect_captchas, solve_on_page, get_balance, and get_supported_captchas. Token-mode solving uses solve_captcha; browser tools such as detect_captchas and solve_on_page require the browser extra and Chromium.

This makes a Cursor reCAPTCHA v2 solver easier to audit. If the agent asks for unsupported behavior, the tool boundary rejects it. If the site key is known, token mode is enough. If the page needs live detection and fill-back, browser mode is the better fit.

Install CapSolver for Cursor

Install the packages from the official GitHub repositories. CapSolver documents that capsolver-mcp depends on capsolver-core, so install core first.

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-mcp.git

For browser mode, install the browser extra and Chromium:

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

Set the API key in the runtime environment rather than in Cursor chat messages:

export CAPSOLVER_API_KEY="YOUR_CAPSOLVER_API_KEY"

The same package stack also supports direct Python code through capsolver-core. CapSolver's Core SDK documentation lists solve, detect, get_captcha_info, solve_on_page, get_balance, and get_supported_captchas as the core methods for controlled automation.

Configure Cursor to Start the MCP Server

In Cursor, add a local MCP server named capsolver. The common stdio configuration uses the capsolver-mcp command and passes the API key through environment variables.

{
  "mcpServers": {
    "capsolver": {
      "command": "capsolver-mcp",
      "env": {
        "CAPSOLVER_API_KEY": "YOUR_CAPSOLVER_API_KEY"
      }
    }
  }
}

If Cursor cannot find capsolver-mcp, point Cursor at the Python executable for the environment where the package is installed:

{
  "mcpServers": {
    "capsolver": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["-m", "capsolver_mcp"],
      "env": {
        "CAPSOLVER_API_KEY": "YOUR_CAPSOLVER_API_KEY"
      }
    }
  }
}

After Cursor reloads the MCP server, verify that tools such as solve_captcha, detect_captchas, solve_on_page, get_balance, and get_supported_captchas appear. If they do not appear, first check the Python path, package installation, and CAPSOLVER_API_KEY environment variable.

Choose Token Mode or Browser Mode

A Cursor reCAPTCHA v2 solver usually follows one of two paths. The correct choice depends on whether your automation already knows the site key.

Token Mode for Known Site Keys

Token mode is the cleaner path when the page URL and reCAPTCHA v2 site key are already known. CapSolver's reCAPTCHA v2 documentation shows ReCaptchaV2TaskProxyLess with websiteURL and websiteKey as required fields for the proxyless task.

import capsolver

capsolver.api_key = "YOUR_CAPSOLVER_API_KEY"

solution = capsolver.solve({
    "type": "ReCaptchaV2TaskProxyLess",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})

print(solution)

In Cursor, the MCP call should pass equivalent information through solve_captcha. Keep the API key in the MCP server environment and keep the site-specific values in the tool call.

Browser Mode for Live Pages

Browser mode is better when Cursor is working with a live page and the agent should not manually extract every parameter. CapSolver Core SDK documents solve_on_page(page) as the all-in-one flow for detection, solving, and fill-back on a Playwright page.

import asyncio
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright

async def main():
    cap = create_capsolver(api_key="YOUR_CAPSOLVER_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 result in results:
            print(result.info.type, result.filled, result.error)
        await browser.close()

asyncio.run(main())

When using capsolver-mcp inside Cursor, the equivalent tool is solve_on_page. Use it only in a controlled browser workflow where your team is authorized to automate the page.

Bonus Code

Redeem Your CapSolver Bonus Code

Boost your automation budget instantly!
Use bonus code CAP26 when topping up your CapSolver account to get an extra 5% bonus on every recharge — with no limits.
Redeem it now in your CapSolver Dashboard

Add Guardrails Before Letting Cursor Call the Tool

A Cursor reCAPTCHA v2 solver should include policy checks before the model can call the tool. The goal is not just to solve a challenge; the goal is to keep automation predictable and auditable.

Keep Secrets Outside the Conversation

Do not paste CAPSOLVER_API_KEY into Cursor chat. Store it in the MCP server environment or a local secret manager. The model only needs to know which tool to call and which non-secret page parameters are approved.

Restrict Targets to Approved Domains

Use an allowlist for domains your workflow is allowed to automate. A good Cursor instruction is: call CapSolver only for these domains, stop for any private or restricted area, and report the reason instead of continuing.

Stop After Bounded Attempts

Set a small retry budget. For example, one token-mode request plus one validation attempt, or one browser-mode solve_on_page attempt plus one page-state check. If the form still fails, return evidence for a developer review.

Troubleshooting Cursor MCP Setup

Most Cursor reCAPTCHA v2 solver failures are configuration issues, not model failures.

The CapSolver Tools Do Not Appear

Check that capsolver-core and capsolver-mcp are installed in the same Python environment Cursor launches. If the command is not on PATH, use the absolute Python path with args: ["-m", "capsolver_mcp"].

Browser Tools Are Missing

Install the browser extra and Chromium. CapSolver documents that browser tools require the [browser] extra and Playwright's Chromium install.

Token Mode Returns No Usable Result

Verify the websiteURL and websiteKey. The reCAPTCHA v2 task documentation recommends submitting the full URL, not just the host. Also confirm that the page really uses reCAPTCHA v2 and not reCAPTCHA v3 or Enterprise-only parameters.

Cursor Keeps Retrying

Add a stop condition to the agent prompt. A responsible Cursor reCAPTCHA v2 solver should not keep calling a solving tool after the same failure repeats.

Compliance and Responsible Use

Use a Cursor reCAPTCHA v2 solver only for lawful, reasonable, and responsible automation. Solving capability does not grant permission to access private, restricted, sensitive, or unauthorized data. Respect site terms, rate limits, robots guidance where applicable, and internal security rules. If the workflow reaches data or account areas outside your authorization, stop the agent and ask for human review.

Conclusion

The best Cursor reCAPTCHA v2 solver is a small MCP integration with strong boundaries. Install capsolver-core, run capsolver-mcp, verify the exposed tools, and choose token mode or browser mode based on the page state. Keep secrets out of prompts, restrict target domains, and log failures for review. For teams building permitted Cursor agents that need reliable CAPTCHA handling, CapSolver gives the MCP service, Core SDK, and task-level reCAPTCHA v2 primitives needed to keep the workflow controlled.

FAQ

Can Cursor call CapSolver without custom integration code?

Yes. With capsolver-mcp, Cursor can discover MCP tools such as solve_captcha, detect_captchas, and solve_on_page after the server is configured.

Should I use token mode or browser mode for reCAPTCHA v2?

Use token mode when the site key and page URL are known. Use browser mode when a Playwright-driven flow needs live detection and fill-back on the page.

Where should I store the CapSolver API key?

Store it in the MCP server environment variable CAPSOLVER_API_KEY, not in Cursor chat messages or model-visible prompts.

Does this support reCAPTCHA v2 Enterprise?

CapSolver's reCAPTCHA v2 documentation lists Enterprise task types. Use only the official task fields documented for the page you are automating.

Is this allowed on any website?

No. Use it only for lawful, reasonable, and responsible workflows where your team has permission to automate the target page.