mcp-captcha-solver

mcp-captcha-solver

Provides browser automation and reCAPTCHA v2 solving tools for AI agents, integrating Selenium and 2Captcha.

Category
Visit Server

README

MCP captcha solver for AI agents

2cap_mcp

Minimal local demo project for showing the architecture:

Agent -> browser/captcha MCP tools -> Selenium helpers -> structured result

The demo page is used as a convenient test stand, while the core idea is a generic reCAPTCHA v2 capability plus browser tools orchestrated by the agent.

Purpose

This repository is a demo for an article and local experiments with MCP plus Selenium. The key idea is:

  • the agent performs a higher-level web task
  • browser tools handle generic page interaction
  • captcha tools remove a reCAPTCHA v2 obstacle when it appears
  • tools use Selenium internally and return normalized results

The agent does not execute low-level browser steps itself.

Current Scope

Current implementation is structured as two capability groups:

  • browser capabilities for the agent's main task flow
  • captcha capabilities for removing reCAPTCHA v2 on the current page

Reference test page:

  • https://2captcha.com/demo/recaptcha-v2

The structure is designed so additional workflows such as Turnstile can be added later without changing the overall architecture.

Project Structure

app/
  browser/
    driver_factory.py
    page_utils.py
  services/
    config.py
    result_models.py
    session_store.py
    solver_client.py
    workflow_catalog.py
  workflows/
    _common.py
    browser.py
    recaptcha_v2.py

mcp_server/
  server.py

How It Works

Responsibilities are split by layer:

  • app/browser/: Selenium driver lifecycle, waits, screenshots, and small browser helpers
  • app/services/: config loading, normalized result models, and external solver adapters
  • app/workflows/: workflow layer split into generic browser tools and reCAPTCHA v2 capability
  • mcp_server/server.py: MCP tools that expose workflows to the agent

This keeps the MCP layer thin and keeps Selenium details out of the agent prompt.

Requirements

  • Python 3.11+
  • Google Chrome installed locally
  • a compatible ChromeDriver available to Selenium
  • 2Captcha API key for the demo workflow

What Needs To Be Installed And Prepared

Before the project can run on another machine, prepare the following:

1. Python

Install Python 3.11+.

Check:

python3 --version

2. Google Chrome

Install a local Chrome browser.

Check on macOS:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version

3. Compatible ChromeDriver

Selenium must be able to start a Chrome instance that matches the installed browser version.

Check:

chromedriver --version

If the browser and driver major versions do not match, Selenium may fail with SessionNotCreatedException.

4. Python Dependencies

Create a virtual environment and install dependencies from requirements.txt.

5. Environment Variables

Create a local .env file from .env.example.

At minimum, set:

  • APIKEY_2CAPTCHA
  • BROWSER_NAME
  • BROWSER_HEADLESS
  • SCREENSHOT_DIR
  • RESULT_DIR
  • CAPTURE_STEP_SCREENSHOTS if you want intermediate screenshots

6. 2Captcha API Key

The captcha_solve_recaptcha_v2 tool depends on a valid 2Captcha API key.

Without it the browser tools will still work, but captcha-solving will return an error.

7. Optional: Claude Desktop Or Another MCP Client

If someone wants to test the full agent-driven scenario rather than only start the MCP server manually, they also need:

  • an MCP-capable client
  • for example Claude Desktop
  • local MCP server configuration pointing to this project

Without an MCP client, the server can still be launched, but there will be no agent connected to call tools.

Installation

Create and activate a virtual environment, then install dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Then copy and fill the environment file:

cp .env.example .env

Configuration

Copy the example env file and fill in your values:

cp .env.example .env

Environment variables:

  • APIKEY_2CAPTCHA: API key for 2Captcha
  • BROWSER_NAME: currently chrome
  • BROWSER_HEADLESS: true or false
  • SCREENSHOT_DIR: where screenshots are stored
  • RESULT_DIR: where extracted verification JSON artifacts are stored
  • CAPTURE_STEP_SCREENSHOTS: true or false; when false, screenshots are captured mainly for errors and final extraction steps

Quick Start Checklist

Before the first run, make sure all of the following are true:

  • Python is installed
  • Chrome is installed
  • ChromeDriver is compatible with the installed Chrome version
  • dependencies from requirements.txt are installed
  • .env exists and contains a valid APIKEY_2CAPTCHA
  • the machine can open a local Chrome browser
  • if using an agent, the MCP client is configured to launch this server

Running The MCP Server

Start the server locally over stdio:

python -m mcp_server.server

Connecting In Claude Desktop

If you want to test the full agent-driven flow in Claude Desktop, the local MCP server must also be registered in Claude's config.

1. Find Claude Desktop config

On macOS the config file is typically:

claude_desktop_config.json

2. Add this MCP server

Add an entry like this to the mcpServers section:

{
  "mcpServers": {
    "mcp-captcha-demo": {
      "command": "/usr/bin/env",
      "args": [
        "python3",
        "/Users/Maksim/Desktop/Работа/projects/example_for_mcp/mcp_server/server.py"
      ],
      "env": {
        "PYTHONPATH": "/Users/Maksim/Desktop/Работа/projects/example_for_mcp",
        "APIKEY_2CAPTCHA": "YOUR_2CAPTCHA_API_KEY",
        "BROWSER_NAME": "chrome",
        "BROWSER_HEADLESS": "true",
        "SCREENSHOT_DIR": "/Users/Maksim/Desktop/Работа/projects/example_for_mcp/artifacts/screenshots",
        "RESULT_DIR": "/Users/Maksim/Desktop/Работа/projects/example_for_mcp/artifacts/results",
        "CAPTURE_STEP_SCREENSHOTS": "false"
      }
    }
  }
}

Notes:

  • use absolute paths
  • if the project lives in a different directory, update all paths accordingly
  • if you already store APIKEY_2CAPTCHA in .env, you can omit it here
  • PYTHONPATH should point to the project root so imports like app.* work

3. Restart Claude Desktop

After editing the config:

  • fully quit Claude Desktop
  • open it again
  • go to Settings -> Developer -> Local MCP servers
  • confirm that mcp-captcha-demo is visible and connected

4. Verify tool loading

In a new Claude chat, ask something like:

Call healthcheck and list_available_workflows.

If the server is connected correctly, Claude should see the exposed browser and captcha tools.

5. Recommended permission behavior

Claude Desktop may ask for permission before tool calls.

For smoother testing:

  • allow tool usage for mcp-captcha-demo
  • prefer Always allow during local demo sessions

Otherwise Claude may pause before almost every browser or captcha action, which makes the agent flow look much less autonomous.

Available Tools

  • healthcheck
  • list_available_workflows
  • browser_open_page
  • browser_get_page_state
  • browser_find_elements
  • browser_click
  • browser_extract_text
  • browser_extract_json
  • browser_click_verify
  • browser_extract_verification_json
  • browser_close_page
  • browser_close_page_on_error
  • captcha_solve_recaptcha_v2

Agent Flow

The preferred agent scenario is:

  1. Call browser_open_page with the target URL
  2. Call browser_get_page_state
  3. If a challenge blocks the task, call captcha_solve_recaptcha_v2
  4. Continue the main task through generic browser tools such as browser_find_elements, browser_click, browser_extract_text, or browser_extract_json
  5. Optionally use browser_click_verify and browser_extract_verification_json for the current 2captcha demo page
  6. Call browser_close_page

The target page URL should come from the user task or agent prompt rather than from server-side default configuration.

Tool Result Format

Tools return a normalized shape like:

{
  "status": "success",
  "workflow": "browser_recaptcha_tools",
  "challenge_type": "recaptcha_v2",
  "page_url": "https://2captcha.com/demo/recaptcha-v2",
  "message": "Verification JSON extracted from the page.",
  "session_id": "18d22b7f3f13485f8f5e3d4f7c9db201",
  "screenshot_path": "artifacts/screenshots/browser_recaptcha_tools-verification-json-20260402-120000.png",
  "verification_payload": {
    "success": true,
    "challenge_ts": "2026-04-06T13:28:26.925Z",
    "hostname": "2captcha.com"
  },
  "verification_result_path": "artifacts/results/browser_recaptcha_tools-verification-20260402-120000.json",
  "details": {
    "verification_payload_present": true
  }
}

On failure, status becomes error, message contains a readable explanation, and screenshot_path is included when available.

Extending The Project

To add a new supported challenge type:

  1. Add more generic browser tools when the agent needs richer continuation actions
  2. Keep generic Selenium primitives in app/browser/
  3. Add provider-specific solving logic to app/services/ only if needed
  4. Expose a new captcha_* tool in mcp_server/server.py only if a new captcha type is needed
  5. Let the agent continue orchestrating browser tools and captcha tools together

The intended model is agent orchestration over two capability sets: generic browser steps and a specialized reCAPTCHA v2 solving capability.

Recommended Servers

playwright-mcp

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official
Featured
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Official
Featured
Local
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

Official
Featured
Local
TypeScript
VeyraX MCP

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official
Featured
Local
graphlit-mcp-server

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official
Featured
TypeScript
Kagi MCP Server

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official
Featured
Python
E2B

E2B

Using MCP to run code via e2b.

Official
Featured
Neon Database

Neon Database

MCP server for interacting with Neon Management API and databases

Official
Featured
Qdrant Server

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official
Featured
Exa Search

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official
Featured