MCP captcha solver for AI agents

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