captcha-mcp
Detects Cloudflare anti-bot protections and locally solves Cloudflare Turnstile CAPTCHA challenges on protected pages.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
captcha-mcp
MCP server giải CAPTCHA 100% tại chỗ — không gọi dịch vụ giải CAPTCHA của bên thứ ba, không gọi API OCR ngoài, không cần cloud solver.
Ba tầng trong một interface:
Solver local — widget CAPTCHA thật chạy trong stealth browser local; token lấy thẳng từ DOM. Với reCAPTCHA v2 image grid, AI (model của agent) đọc ảnh rồi solver click và lấy token.
Stealth — TLS fingerprint (
curl_cffi), stealth browser (nodriver / cloakbrowser), hành vi người (Bezier mouse, nhịp gõ phím).Detection — chẩn đoán anti-bot vendor, CAPTCHA nào đang chặn, fingerprint có mâu thuẫn không.
Lý do có tầng 2-3: CAPTCHA chỉ là cửa ải cuối. Anti-bot hiện đại chặn bạn trước khi CAPTCHA xuất hiện, dựa trên sự nhất quán của TLS + UA + canvas + WebGL + hành vi.
Transport: stdio (mặc định) · sse · streamable-http.
Install
uvx captcha-mcp # chạy luôn, không càiHoặc từ source:
git clone https://github.com/you/captcha-mcp.git && cd captcha-mcp
uv pip install -e ".[dev]" # thêm stealth: ".[dev,stealth]"
captcha-mcpPhụ thuộc ngoài (đều chạy offline):
Cần cho | Cài cách |
stealth browser |
|
TLS impersonation |
|
OCR image captcha |
|
Related MCP server: cloakbrowser-mcp
Config
Tất cả biến prefix CAPTCHA_:
Biến | Mặc định | Ý nghĩa |
|
| giây chờ token của widget |
|
| giây chờ sau khi navigate |
|
|
|
|
| tesseract page segmentation mode |
|
| dưới ngưỡng này → trả ảnh cho AI đọc |
|
|
|
|
| |
|
|
|
|
| giây |
| – | proxy mặc định (Turnstile hay ràng buộc IP) |
|
|
|
Copy .env.example → .env. Server start được với config rỗng.
Tool list
Solver (local)
Tool | Input | Trả về |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
status: ready · needs_ai · challenge_interactive · timeout · not_found · error.
Luồng AI-in-the-loop (reCAPTCHA v2 image grid):
1. solve_recaptcha_v2(page_url=...)
→ status="needs_ai", meta.instruction="Select all traffic lights",
meta.tiles=[{index:0, path:"/root/.cache/captcha-mcp/ab12.png"}, ...]
2. Agent đọc các ảnh (tool Read / vision) → tự chọn ô
3. submit_recaptcha_v2(challenge_id="cap-xxx", tiles=[1,4,7])
→ {status:"ready", token:"03AGdBq26..."}Có OCR sẵn thì solve_image_captcha trả status="ready" kèm text luôn; nếu confidence
thấp thì trả status="needs_ai" + meta.image_path để AI đọc.
reCAPTCHA v2 image grid — AI đọc ảnh
1. solve_recaptcha_v2(page_url=...)
→ status="needs_ai",
meta.instruction="Select all images with a fire hydrant",
meta.challenge_image="/root/.cache/captcha-mcp/ab12.png" ← ảnh đã đánh số từng ô
meta.tiles=[{index:0,path:"..."}, ...]
2. Agent đọc ảnh (vision) → chọn ô
3. submit_recaptcha_v2(challenge_id="cap-xxx", tiles=[0,1])
→ {status:"ready", token:"03AGdBq26..."}Yêu cầu: client phải có model vision (đọc được ảnh). Đây là phần "AI giải" — không có dịch vụ ngoài, dùng đúng model của agent đang chạy.
Cơ chế đã kiểm chứng trên reCAPTCHA v2 thật (Google demo):
mở popup challenge (click checkbox bằng input event thật) ✓
dò lưới ô chính xác 9/9 (3×3) và 12/12 (3×4) bằng phân tích pixel ✓
click rơi đúng ô (dấu tick xanh xuất hiện đúng ở ô AI chọn) ✓
bấm VERIFY → Google đánh giá → trả challenge mới → vòng lặp tiếp tục ✓
nếu Google đổi ảnh trong lúc AI đọc → tool phát hiện bằng hash ảnh và trả ảnh mới (
meta.stale) thay vì áp đáp án cũ ✓chọn sai → không sinh token giả, trả
status="timeout"+ ảnh mới ✓
Độ chính xác cuối cùng phụ thuộc khả năng đọc ảnh của model của client (ô ảnh nhỏ, nhiễu).
Image captcha — OCR local (đã hoàn chỉnh, không cần vision)
{ "tool": "solve_image_captcha", "args": { "image_base64": "<base64 png>" } }
// → { "status": "ready", "text": "A7B9", "meta": { "ocr_backend": "tesseract", "confidence": 92 } }
// confidence thấp → { "status": "needs_ai", "meta": { "image_path": "..." } }Dùng tesseract (CLI) hoặc ddddocr — cả hai chạy offline, không gọi API ngoài.
Stealth
Tool | Input chính | Trả về |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| – |
|
actions[]: {"type":"click","selector":"#b"}, {"type":"type","selector":"#q","text":"abc"},
{"type":"scroll","y":800}, {"type":"wait","seconds":1}, {"type":"press","key":"Enter"}.
Detection
Tool | Input chính | Trả về |
|
|
|
|
|
|
|
|
|
JSON schema đầy đủ được sinh tự động từ FastMCP.
Luồng dùng điển hình
detect_antibot(url)→ biết trang bị chặn bởi gì (Cloudflare / DataDome / PerimeterX…), có CAPTCHA nào, có challenge không.Không có anti-bot mạnh →
stealth_http_request(url)(nhanh, TLS giả).Có JS challenge →
launch_stealth_browser()→stealth_navigate()→browse_with_humanization().Có CAPTCHA →
solve_turnstile()/solve_recaptcha_v3()(token local).reCAPTCHA v2 image grid →
solve_recaptcha_v2()→ AI đọc ảnh →submit_recaptcha_v2().Vẫn bị chặn →
get_fingerprint_report(browser_id)xem chỗ nào đang mâu thuẫn (UA Windows nhưng WebGL SwiftShader, UA "HeadlessChrome"…).
Client config
Claude Desktop — examples/claude_desktop_config.json:
{
"mcpServers": {
"captcha": {
"command": "uvx",
"args": ["captcha-mcp"],
"env": { "CAPTCHA_STEALTH_BACKEND": "nodriver" }
}
}
}Cursor — examples/cursor_config.json, Cline — examples/cline_config.json.
SSE (nhiều agent cùng dùng):
MCP_TRANSPORT=sse captcha-mcp
# → http://localhost:8000/sseKiến trúc
src/captcha_mcp/
├── server.py # FastMCP — đăng ký TẤT CẢ tool
├── config.py # Settings (env-based)
├── solvers/
│ ├── base.py # SolveResult / SolveStatus
│ ├── browser_solver.py# widget non-interactive (Turnstile / reCAPTCHA v3 / hCaptcha)
│ ├── ai_solver.py # reCAPTCHA v2 grid: trích ảnh ô → AI đọc → click → token
│ ├── ocr_solver.py # image captcha qua tesseract / ddddocr (local)
│ └── _cdp.py # CDP isolated world / OOPIF session (đọc trong iframe cross-origin)
├── stealth/
│ ├── browser.py # nodriver / cloakbrowser wrapper + registry
│ ├── tls_client.py # curl_cffi impersonate (JA3/JA4), fallback httpx
│ ├── humanize.py # Bezier mouse, delay ngẫu nhiên, nhịp gõ phím
│ └── interaction.py # click/type/scroll/press với hành vi người
├── detection/
│ ├── antibot.py # vendor/anti-bot/CAPTCHA/fingerprint signals
│ ├── fingerprint.py # đọc signals + chấm điểm nhất quán (coherence)
│ └── behavioral.py # phát hiện pattern hành vi robotic
└── utils.py # lưu ảnh cache, helperVì sao thiết kế thế
Không phụ thuộc dịch vụ ngoài: không cần key, không tốn tiền/请求, không rò dữ liệu ra ngoài. Đổi lại: phần "AI đọc image grid" cần model của agent có vision — đó là AI của bạn, chạy sẵn.
Browser là nguồn sự thật: token được widget thật sinh ra và nằm trong DOM → ta đọc, không mô phỏng token.
Cross-origin iframe: reCAPTCHA iframe là OOPIF → dùng
Target.attachToTarget+Runtime.evaluatevớisessionId(solvers/_cdp.py), không đụng WebDriver.Detection chỉ báo cáo, không bypass:
detect_antibotđể agent hiểu môi trường, không tự động vượt mọi thứ.Fingerprint phải nhất quán:
get_fingerprint_reportchỉ ra mâu thuẫn — đây là thứ Cloudflare/DataDome kiểm kỹ nhất.curl_cffikhông thay browser: nó chỉ giải quyết TLS/HTTP2. JS challenge vẫn cần browser.
Dev
make install
make test # pytest + respx mock, không cần mạng
make lintCI: file workflow nằm ở docs/github-actions/. Copy sang .github/workflows/ để chạy
GitHub Actions. (Lưu ý: push file .github/workflows/ bằng OAuth app token sẽ bị GitHub
từ chối nếu token thiếu scope workflow — khi đó dùng PAT hoặc SSH key.)
⚠️ Disclaimer
Tool này tự giải tại chỗ: không bọc dịch vụ trả phí, không gọi API ngoài.
Chỉ dùng cho việc hợp pháp: test bảo mật có uỷ quyền, automation nội bộ của bạn, QA.
Lớp stealth/detection dùng để chẩn đoán và test trên hệ thống của bạn hoặc hệ thống được cấp quyền kiểm thử.
Vượt anti-bot/CAPTCHA để vượt kiểm soát truy cập trái phép là vi phạm pháp luật ở nhiều nước (bao gồm CFAA và nghị định EU) — tool không bảo vệ bạn khỏi trách nhiệm pháp lý này.
Không dùng cho spam, credential stuffing, vượt rate limit, hay bất kỳ hành vi gây thiệt hại nào.
Người dùng tự chịu trách nhiệm hoàn toàn về mục đích sử dụng.
License
MIT — xem LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Solve reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile and image captchas. Platform-hosted, no creden
Solve reCAPTCHA image grids, text captchas, GeeTest and FunCAPTCHA for AI agents. Free tier.
Browser agents and stealth cloud browsers for AI: run web tasks, fill forms, extract data.
Undetectable cloud browser sessions for AI agents and scrapers. Navigate, extract, click, captcha.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to perform undetectable browser automation that bypasses Cloudflare, antibots, and social media blocks. Provides 105 tools for element extraction, network debugging, and real-world web scraping with a 98.7% success rate on protected sites.170 PyPI3,382MIT
- AlicenseAqualityDmaintenanceStealth browser automation for AI agents, using source-patched Chromium to bypass bot detection systems like Cloudflare, reCAPTCHA, and FingerprintJS.28Apache 2.0
- FlicenseNot gradedqualityNot gradedmaintenanceProvides AI-powered undetectable browser automation for data harvesting, bypassing protections like Cloudflare, and intercepting network traffic, with 90 tools for element interaction, extraction, and network debugging.3-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to perform stealth browser automation and anti-detection web interaction, including session management, humanized interactions, and bypassing anti-bot/WAF protections.MIT