Skip to main content
Glama

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:

  1. 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.

  2. Stealth — TLS fingerprint (curl_cffi), stealth browser (nodriver / cloakbrowser), hành vi người (Bezier mouse, nhịp gõ phím).

  3. 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ài

Hoặ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-mcp

Phụ thuộc ngoài (đều chạy offline):

Cần cho

Cài cách

stealth browser

pip install 'captcha-mcp[stealth]' (nodriver) — cần Chrome/Chromium có sẵn

TLS impersonation

curl_cffi (đã nằm trong deps chính)

OCR image captcha

apt install tesseract-ocr hoặc pip install ddddocr

Related MCP server: cloakbrowser-mcp

Config

Tất cả biến prefix CAPTCHA_:

Biến

Mặc định

Ý nghĩa

CAPTCHA_WIDGET_TIMEOUT

30

giây chờ token của widget

CAPTCHA_PAGE_WAIT

2.0

giây chờ sau khi navigate

CAPTCHA_OCR_BACKEND

auto

auto | tesseract | ddddocr

CAPTCHA_OCR_PSM

7

tesseract page segmentation mode

CAPTCHA_OCR_MIN_CONFIDENCE

60

dưới ngưỡng này → trả ảnh cho AI đọc

CAPTCHA_STEALTH_BACKEND

nodriver

nodriver | cloakbrowser

CAPTCHA_STEALTH_HEADLESS

true

CAPTCHA_TLS_IMPERSONATE

chrome

chrome | chrome124 | firefox | safari | edge

CAPTCHA_HTTP_TIMEOUT

30

giây

CAPTCHA_PROXY_URL

–

proxy mặc định (Turnstile hay ràng buộc IP)

MCP_TRANSPORT

stdio

stdio | sse | streamable-http

Copy .env.example → .env. Server start được với config rỗng.

Tool list

Solver (local)

Tool

Input

Trả về

solve_turnstile

site_key, page_url, timeout?, headless?, backend?, proxy_url?

{status, token, error, meta}

solve_recaptcha_v3

site_key, page_url, action?, ...

{status, token, ...}

solve_hcaptcha

site_key, page_url, ...

{status, token, ...}

solve_recaptcha_v2

page_url, site_key?, ...

{status: ready | needs_ai, token | meta.tiles}

submit_recaptcha_v2

challenge_id, tiles: list[int]

{status, token}

close_captcha_challenge

challenge_id

{status}

solve_image_captcha

image_base64, instructions?

{status, text, meta.image_path}

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ề

stealth_http_request

url, method?, impersonate?, headers?, data?, json_body?, proxy?

{status, text, headers, tls_fingerprint}

launch_stealth_browser

headless?, backend?, proxy?

{status, browser_id}

stealth_navigate

browser_id, url, wait?

{status, url}

stealth_evaluate

browser_id, script

{status, result}

stealth_snapshot

browser_id

{status, html, cookies, title}

browse_with_humanization

browser_id, actions[], humanize?

{status, actions[]}

close_stealth_browser

browser_id

{status}

list_stealth_browsers

–

{browsers[]}

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ề

detect_antibot

page_url, impersonate?

{antibot[], captchas[], fingerprint_signals[], challenge_page, blocked, confidence}

get_fingerprint_report

browser_id

{signals, coherence:{consistency_score, findings[], verdict}}

analyze_behavior

events[]

{robot_probability, verdict, metrics, findings[]}

JSON schema đầy đủ được sinh tự động từ FastMCP.

Luồng dùng điển hình

  1. detect_antibot(url) → biết trang bị chặn bởi gì (Cloudflare / DataDome / PerimeterX…), có CAPTCHA nào, có challenge không.

  2. Không có anti-bot mạnh → stealth_http_request(url) (nhanh, TLS giả).

  3. Có JS challenge → launch_stealth_browser() → stealth_navigate() → browse_with_humanization().

  4. Có CAPTCHA → solve_turnstile() / solve_recaptcha_v3() (token local).

  5. reCAPTCHA v2 image grid → solve_recaptcha_v2() → AI đọc ảnh → submit_recaptcha_v2().

  6. 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/sse

Kiế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, helper

Vì 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.evaluate với sessionId (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_report chỉ ra mâu thuẫn — đây là thứ Cloudflare/DataDome kiểm kỹ nhất.

  • curl_cffi khô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 lint

CI: 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 PyPI
      3,382
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Stealth browser automation for AI agents, using source-patched Chromium to bypass bot detection systems like Cloudflare, reCAPTCHA, and FingerprintJS.
      28
      Apache 2.0
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides 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
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to perform stealth browser automation and anti-detection web interaction, including session management, humanized interactions, and bypassing anti-bot/WAF protections.
      MIT