# MCP captcha solver for AI agents

![2cap_mcp](image/2cap_mcp.svg)

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

```text
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:

```bash
python3 --version
```

### 2. Google Chrome

Install a local Chrome browser.

Check on macOS:

```bash
/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:

```bash
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`](/Users/Maksim/Desktop/Работа/projects/example_for_mcp/requirements.txt).

### 5. Environment Variables

Create a local `.env` file from [`.env.example`](/Users/Maksim/Desktop/Работа/projects/example_for_mcp/.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:

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

Then copy and fill the environment file:

```bash
cp .env.example .env
```

## Configuration

Copy the example env file and fill in your values:

```bash
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:

```bash
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`](/Users/Maksim/Library/Application%20Support/Claude/claude_desktop_config.json)

### 2. Add this MCP server

Add an entry like this to the `mcpServers` section:

```json
{
  "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:

```text
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:

```json
{
  "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.