2Captcha MCP

2Captcha MCP

通过 stdio 向 Claude Code 提供 完整的 2Captcha API 功能：31 种验证码类型、5 个管理工具、3 个 pingback CRUD 工具、3 个 webhook 事件存储工具，以及 1 个组合式解答并等待工具（共 43 个工具）。

基于官方 2captcha-python SDK（AsyncTwoCaptcha）构建，因此重试、轮询和解析均由上游处理；SDK 支持的所有验证码类型都能在 SDK 添加后立即使用。

快速开始

pip install twocaptcha-mcp
# or for development:
pip install -e ".[dev]"

在项目根目录旁创建 .env：

2Captcha_API_KEY=your_2captcha_key_here

验证是否正常运行：

python -m twocaptcha_mcp           # starts the stdio server (Ctrl+C to stop)

将服务注册到 Claude Code：

claude mcp add 2captcha -e 2Captcha_API_KEY=your_2captcha_key_here -- python -m twocaptcha_mcp

重启 claude 后，向模型发送提示词：

“使用 twocaptcha_balance 检查我的账户。”

配置

所有设置均通过环境变量配置。别名按优先级排列：

设置	别名	默认值	范围
API 密钥（必填）	2Captcha_API_KEY、TWOCAPTCHA_API_KEY、2CAPTCHA_API_KEY、API_KEY_2CAPTCHA	—	—
服务	TWOCAPTCHA_SERVER	2captcha.com	2captcha.com、rucaptcha.com
默认超时	TWOCAPTCHA_DEFAULT_TIMEOUT	120 s	1..600
reCAPTCHA 超时	TWOCAPTCHA_RECAPTCHA_TIMEOUT	600 s	1..1200
轮询间隔	TWOCAPTCHA_POLLING_INTERVAL	10 s	1..120
Soft id	TWOCAPTCHA_SOFT_ID	4580	—
日志级别	TWOCAPTCHA_LOG_LEVEL	INFO	DEBUG/INFO/WARNING/ERROR/CRITICAL
默认 pingback URL	TWOCAPTCHA_DEFAULT_CALLBACK	未设置	https URL

工具

验证码求解器（31）

工具	SDK 方法	必需参数
twocaptcha_solve_normal	normal	file_path 或 file_base64
twocaptcha_solve_text	text	text
twocaptcha_solve_audio	audio	file（二选一），audio_lang
twocaptcha_solve_grid	grid	file（二选一）
twocaptcha_solve_canvas	canvas	file（二选一）
twocaptcha_solve_coordinates	coordinates	file（二选一）
twocaptcha_solve_rotate	rotate	files: list
twocaptcha_solve_vkimage	vkimage	files，steps
twocaptcha_solve_recaptcha	recaptcha	sitekey，url，version，enterprise
twocaptcha_solve_hcaptcha	hcaptcha	sitekey，url
twocaptcha_solve_turnstile	turnstile	sitekey，url（CF Challenge 还需 data/pagedata）
twocaptcha_solve_funcaptcha	funcaptcha	sitekey，url
twocaptcha_solve_geetest	geetest	gt，challenge，url
twocaptcha_solve_geetest_v4	geetest_v4	captcha_id，url
twocaptcha_solve_capy	capy	sitekey，url
twocaptcha_solve_keycaptcha	keycaptcha	s_s_c_user_id，s_s_c_session_id，两个 sign，url
twocaptcha_solve_lemin	lemin	captcha_id，div_id，url
twocaptcha_solve_mtcaptcha	mtcaptcha	sitekey，url
twocaptcha_solve_friendly_captcha	friendly_captcha	sitekey，url
twocaptcha_solve_cutcaptcha	cutcaptcha	misery_key，apikey，url
twocaptcha_solve_amazon_waf	amazon_waf	sitekey，iv，context，url
twocaptcha_solve_tencent	tencent	app_id，url
twocaptcha_solve_atb_captcha	atb_captcha	app_id，api_server，url
twocaptcha_solve_datadome ⚑	datadome	proxy，user_agent，captcha_url，pageurl
twocaptcha_solve_captchafox ⚑	captchafox	proxy，user_agent，sitekey，pageurl
twocaptcha_solve_vkcaptcha ⚑	vkcaptcha	proxy，user_agent，redirect_uri
twocaptcha_solve_prosopo	prosopo	sitekey，pageurl
twocaptcha_solve_temu	temu	body，part1..3
twocaptcha_solve_altcha	altcha	pageurl
twocaptcha_solve_cybersiara	cybersiara	master_url_id，pageurl，cyber_user_agent
twocaptcha_solve_yandex_smart	yandex_smart	sitekey，url

⚑ — SDK 签名要求必须提供 proxy 和 user_agent。

所有求解器工具都接受相同的一组可选 kwargs（mixin SolverKwargs）：

• proxy: {type, uri}（HTTP/HTTPS/SOCKS4/SOCKS5）
• pingback: HttpUrl — 单次调用的 pingback URL（必须预先注册）
• soft_id: int
• cookies: str
• user_agent: str
• lang: str
• header_acao: 0|1

管理（5）

• twocaptcha_balance — 当前余额（USD）
• twocaptcha_report_good / twocaptcha_report_bad — 在 15 分钟内报告验证码 ID
• twocaptcha_get_result — 手动轮询验证码 ID（与 send_raw 配合使用）
• twocaptcha_send_raw — 用于调用此服务尚未公开的 SDK 方法的应急入口

Pingback 增删改查（3）

• twocaptcha_register_pingback — 将回调 URL 加入白名单
• twocaptcha_list_pingbacks — 列出白名单地址
• twocaptcha_delete_pingback — 删除一个地址或使用 addr="all" 删除全部

开发

pytest --cov=twocaptcha_mcp --cov-branch --cov-fail-under=92 -v
ruff check . && ruff format --check .
mypy --strict twocaptcha_mcp

针对真实的 2Captcha API 运行实时测试（会消耗额度）：

pytest -m live --run-live          # balance + solve_normal + concurrent_balance
pytest -m e2e --run-e2e             # full MCP protocol roundtrip via mcp.client.session

架构

twocaptcha_mcp/
├── __main__.py            # stdio entrypoint
├── server.py              # build_server + dispatch_tool_call
├── config.py              # pydantic-settings (.env)
├── logger.py              # stderr-only logger (stdout is reserved for stdio MCP)
├── client/
│   ├── solver.py          # SolverClient — async wrapper over AsyncTwoCaptcha
│   ├── pingback.py        # httpx wrapper for legacy res.php
│   ├── rate_limiter.py    # async sliding-window per-method rate limiter
│   └── errors.py          # internal CaptchaError hierarchy
├── schemas/               # Pydantic request/response models per captcha family
├── tools/                 # @captcha_tool handlers per captcha family + composite
└── webhook_receiver/      # Starlette app + SQLite store (twocaptcha-mcp-webhook)

工具处理程序仅依赖 SolverClient / PingbackClient 抽象，不会从处理程序中导入 SDK。添加一种新的验证码类型分为 3 个步骤：架构 → 工具处理程序 → 增加快照测试数量。

Webhook 接收器（可选，自 0.3.0 起）

对于长时间运行的求解（recaptcha v3 最长可达 600 s），轮询模式下的 SDK 调用会在整个过程中占用 MCP 请求槽位。运行可选的 twocaptcha-mcp-webhook 服务，即可切换为 pingback 模式——2Captcha 会将结果 POST 到你的 URL，接收器将其写入 SQLite，MCP 工具则可以异步读取，不会阻塞。

• 组合工具：twocaptcha_solve_and_wait_pingback 发送验证码并等待本地存储中的结果
• 读取工具：twocaptcha_pingback_events_list/get/clear
• 部署：docs/DEPLOY-WEBHOOK.md
• 故障排除：TROUBLESHOOTING.md

贡献

有关开发流程、代码规范以及 MCP 工具接口的 SemVer 政策，请参阅 CONTRIBUTING.md。

安全

请参阅 SECURITY.md。请通过 GitHub Security Advisory 私下报告漏洞。

许可证

MIT — 请参阅 LICENSE。

---

_{注册表验证 — mcp-name: io.github.aruxojuyu665/twocaptcha-mcp}