mcp-captcha-solver
Provides browser automation and reCAPTCHA v2 solving tools for AI agents, integrating Selenium and 2Captcha.
README
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 v2obstacle 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 v2on 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 helpersapp/services/: config loading, normalized result models, and external solver adaptersapp/workflows/: workflow layer split into generic browser tools andreCAPTCHA v2capabilitymcp_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_2CAPTCHABROWSER_NAMEBROWSER_HEADLESSSCREENSHOT_DIRRESULT_DIRCAPTURE_STEP_SCREENSHOTSif 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 2CaptchaBROWSER_NAME: currentlychromeBROWSER_HEADLESS:trueorfalseSCREENSHOT_DIR: where screenshots are storedRESULT_DIR: where extracted verification JSON artifacts are storedCAPTURE_STEP_SCREENSHOTS:trueorfalse; whenfalse, 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.txtare installed .envexists and contains a validAPIKEY_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:
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_2CAPTCHAin.env, you can omit it here PYTHONPATHshould point to the project root so imports likeapp.*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-demois 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 allowduring 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
healthchecklist_available_workflowsbrowser_open_pagebrowser_get_page_statebrowser_find_elementsbrowser_clickbrowser_extract_textbrowser_extract_jsonbrowser_click_verifybrowser_extract_verification_jsonbrowser_close_pagebrowser_close_page_on_errorcaptcha_solve_recaptcha_v2
Agent Flow
The preferred agent scenario is:
- Call
browser_open_pagewith the target URL - Call
browser_get_page_state - If a challenge blocks the task, call
captcha_solve_recaptcha_v2 - Continue the main task through generic browser tools such as
browser_find_elements,browser_click,browser_extract_text, orbrowser_extract_json - Optionally use
browser_click_verifyandbrowser_extract_verification_jsonfor the current 2captcha demo page - 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:
- Add more generic browser tools when the agent needs richer continuation actions
- Keep generic Selenium primitives in
app/browser/ - Add provider-specific solving logic to
app/services/only if needed - Expose a new
captcha_*tool inmcp_server/server.pyonly if a new captcha type is needed - 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
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
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.
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.
VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
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.
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.
E2B
Using MCP to run code via e2b.
Neon Database
MCP server for interacting with Neon Management API and databases
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.
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.