Решение MTCaptcha на Python: sitekey, токен и отправка формы

Чтобы справиться с MTCaptcha на Python без браузера, загрузите страницу входа через requests, прочитайте sitekey и action из её объекта mtcaptchaConfig, передайте оба значения в solver.mtcaptcha() из CapSkip SDK и отправьте полученный токен в поле mtcaptcha-verifiedtoken при отправке формы. За вызовом стоит решатель капчи CapSkip для MTCaptcha, который работает на вашем собственном ПК с Windows по фиксированной лицензии, поэтому отклонённый токен обходится вам лишь в ещё один проход цикла.
Что понадобится
- ПК с Windows и CapSkip 4.3.0 (9 ноября 2026 года, первый выпуск с MTCaptcha) или новее. Установить его поможет руководство по настройке с описанием установки. Копия на моём ПК приняла метод mt_captcha, но прочитать её версию я не смог.
- Python 3.10 или новее (это минимум, объявленный в capskip 1.7.0), requests 2.34.2 и urllib3 2.8.0, а также capskip 1.7.0 или новее, первая версия с методом для MTCaptcha. Я запускал их только на Python 3.11.7, 3.13.7 и 3.14.0.
- Оба пакета устанавливаются из PowerShell командой python -m pip install capskip requests (py -m pip тоже подойдёт), поэтому pip не обязан быть в вашем PATH.
- Адрес для CapSkip. В режиме Local (127.0.0.1) до него дотянется только ПК, на котором запущен CapSkip. Режим Server добавляет вашу сеть или публичный IP, и тогда другой ПК или Windows VPS может отправлять те же запросы. Оба режима описаны в разделе Настройки подключения руководства по настройке. Оставьте любую настройку Service Emulator в значении по умолчанию: SDK обращается к CapSkip в его формате по умолчанию, а эмулируемый сервис может отвечать иначе.
Я проверял этот скрипт на двух имитациях, которые написал сам: одна играет CapSkip, другая сайт с входом. Настоящее приложение CapSkip на моём ПК приняло три задания MTCaptcha с публичным демо-sitekey и адресом страницы из собственного примера SDK, чтобы получить настоящий токен и замерить вызов SDK. Ни один сайт не проверял токен, поэтому ничто здесь не показывает, что настоящий сайт его примет, а все правила сайта в имитации мои. О том, как сайт проверяет токен, рассказано в руководстве MTCaptcha по проверке токена.
Шаг 1: настройка сессии и поиск sitekey MTCaptcha
Сохраните первый блок кода как mtcaptcha_login.py. Каждый следующий блок, включая следующий в этом шаге, добавляется в конец того же файла в показанном порядке, и после шага 4 файл будет готов. Одна строка User-Agent обслуживает загрузку страницы, решение и отправку формы, поэтому подойдёт любая актуальная строка браузера. В режиме Server укажите адрес вашего сервера в host. Если включена API Key Validation, передайте также свой ключ как apiKey.
# python -m pip install capskip requests
import re
import requests
from capskip import ApiException, CapSkip
LOGIN_URL = "https://example.com/login" # the page that shows the widget
USER_AGENT = (
"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
"(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36"
)
# Local mode. In Server mode, use your server's address as the host.
solver = CapSkip(host="127.0.0.1", port=8080)Большинство страниц MTCaptcha настраивают виджет встроенным объектом mtcaptchaConfig, где значение sitekey начинается с MTPublic-, и там же может быть задан action. Демо-страница CapSkip пишет его в одну строку с ключом lang, тремя callback и без action. Документация CapSkip растягивает его на несколько строк и добавляет action. Другие страницы используют одинарные кавычки и ключи без кавычек. Функция ниже ищет каждый ключ по имени, поэтому читает все эти варианты, но её собьёт встроенная функция внутри объекта или скрипт, в котором объект не заканчивается закрывающей скобкой с точкой с запятой или закрывающим тегом script.
Она выдаёт ошибку, если на странице нет такого объекта или в нём нет sitekey, и первый случай вполне реальный. GET-запрос к демо-странице 2Captcha вернул HTML, в котором sitekey встречается только в инструкциях. Для такой страницы один раз скопируйте sitekey из адреса iframe виджета: это параметр запроса sitekey на service.mtcaptcha.com. Если страница задаёт action, отправьте его: в документации MTCaptcha по action сказано, что вызов проверки сообщает action, с которым запущен виджет, так что сайт может его сравнить. Если страница его не задаёт, не отправляйте ничего.
def read_config(html):
"""Return (sitekey, action) from the page's mtcaptchaConfig object."""
found = re.search(r"mtcaptchaConfig\s*=\s*\{(.*?)(?:\}\s*;|</script>)", html, re.S)
if not found:
raise RuntimeError("no mtcaptchaConfig in the page source")
def value(name):
pattern = r"(?<![\w-])[\"']?" + name + r"[\"']?\s*:\s*[\"']([^\"']+)[\"']"
pair = re.search(pattern, found.group(1))
return pair.group(1) if pair else None
sitekey = value("sitekey")
if not sitekey:
raise RuntimeError("no sitekey in mtcaptchaConfig")
return sitekey, value("action")Я запускал read_config на трёх стилях кавычек из моей имитации, на вложенном объекте перед sitekey и перед action, на конфиге без завершающей точки с запятой и на сохранённых копиях двух публичных страниц. Демо-страница CapSkip дала sitekey и не дала action, а демо-страница 2Captcha вызвала описанную выше ошибку. Все три версии Python дали одинаковый результат.
Шаг 2: запрос токена через SDK
Вы вызываете solver.mtcaptcha(sitekey, url, **options). Он отправляет задание, опрашивает результат и возвращает словарь, поэтому писать цикл не нужно. В url передайте настоящий адрес страницы, потому что MTCaptcha выдаёт токены только для доменов, на которые зарегистрирован sitekey. Добавьте эту функцию в конец файла. Она добавляет action, только если страница его задаёт.
def get_token(sitekey, action):
options = {"userAgent": USER_AGENT}
if action: # only when the page's config sets one
options["action"] = action
return solver.mtcaptcha(sitekey, LOGIN_URL, **options)["token"]Перед любой отправкой SDK проверяет ваши аргументы. Sitekey не вида MTPublic- плюс до 55 букв, цифр, дефисов или подчёркиваний, адрес страницы, не являющийся абсолютным URL с http или https, и параметр, которого не принимает API MTCaptcha (например, invisible), сразу вызывают ValidationException. Sitekey, вставленный как sk=MTPublic-, принимается, и SDK убирает префикс.
В трёх настоящих запусках словарь содержал ключи "captchaId", "code" и "token", причём последние два содержат одну и ту же строку, ту самую, что идёт в mtcaptcha-verifiedtoken. Каждый настоящий токен начинался с v1( и заканчивался на **), имел длину 418 символов и пять полей, разделённых запятыми, третье из которых было sitekey. В документации приведены более короткие образцы, поэтому не проверяйте токен по длине.
Параметр userAgent задаёт строку браузера, которую CapSkip предъявляет MTCaptcha. Я передаю собственную строку сессии, чтобы решение, загрузка страницы и отправка формы выглядели как один браузер. Без него CapSkip использует строку Chrome для Windows. Ничто из прочитанного мной не говорит, что MTCaptcha сравнивает эти две строки, и я это не проверял. В актуальной документации API для User-Agent, который нельзя использовать для задания, указан ERROR_WRONG_USERAGENT, а настоящее приложение моего параметра userAgent так и не увидело, поэтому если придёт эта ошибка, уберите параметр из get_token.
Время от момента перед вызовом до его возврата: 3.77 секунды один раз на Python 3.14.0 и 3.76 секунды дважды на 3.11.7, с capskip 1.7.0, опросом по умолчанию и настоящим приложением CapSkip на Windows 11. Эти три вызова не отправляли ни userAgent, ни action. На эту цифру влияет расписание опроса в SDK: на имитации он запрашивал результат через 0, 0.25, 0.76, 1.76, 3.76 и 7.76 секунды после отправки, а токен имитации, готовый в любой момент от 1.9 до 3.6 секунды, возвращался на 3.76. Значит, настоящее решение завершилось между опросами на 1.76 и 3.76 секунды, а три запуска не являются бенчмарком.
Для решения MTCaptcha браузер не запускается, поэтому SDK ждёт столько, сколько позволяет его defaultTimeout, по умолчанию 120 секунд. При defaultTimeout, сниженном до 6 секунд, имитация, которая так и не ответила, вызвала TimeoutException через 7.78 секунды после вызова, потому что последняя пауза между опросами вышла за предел.
Шаг 3: отправка формы, пока токен свежий
В браузере виджет записывает токен в скрытый input с именем mtcaptcha-verifiedtoken. Без браузера вы отправляете это поле сами, рядом с собственными полями формы. Функция ниже, тоже добавляемая в конец файла, делает именно это. Сессия переносит cookie страницы в отправку формы. Если атрибут action формы указывает на другой адрес, измените первый аргумент вызова session.post.
Токен действует один раз и лишь короткое время. В руководстве MTCaptcha по проверке токена сказано, что обычно токен действителен несколько минут, но срок по умолчанию составляет от 60 до 120 секунд, и по умолчанию его можно проверить только один раз, поэтому отправьте его в течение минуты. Документация CapSkip просит запрашивать токен непосредственно перед отправкой формы, поэтому get_token выполняется после загрузки страницы, а отправка формы идёт сразу за ним. Если вы добавляете собственную паузу, решайте после неё. Отклонённый токен потрачен, поэтому цикл из шага 4 запрашивает новый.
Отправка формы также указывает страницу в заголовке Referer, потому что requests не отправляет ни Referer, ни Origin, а некоторые фреймворки отклоняют отправку формы по HTTPS без них обоих. Моя имитация изображает такой фреймворк, и без заголовка она отвечала 403.
def post_form(session, token, username, password):
return session.post(
LOGIN_URL,
data={
"username": username, # your form's own fields go here
"password": password,
"mtcaptcha-verifiedtoken": token,
},
headers={"Referer": LOGIN_URL}, # requests sends none by itself
timeout=30,
)Шаг 4: полный скрипт входа для MTCaptcha на Python
Добавьте последний блок в конец mtcaptcha_login.py, после чего файл будет готов. Задайте LOGIN_URL и запустите python mtcaptcha_login.py (или py mtcaptcha_login.py). Две строки здесь служат заглушками для вашего сайта: "Welcome" (текст, который показывает успешный вход) и "captcha check failed" (фраза, которая есть в собственном отказе вашего сайта по капче). Скрипт сдаётся после трёх попыток.
Согласно документации CapSkip, на ERROR_CAPTCHA_UNSOLVABLE отвечают отправкой нового задания, и скрипт повторяет только этот код. В документации названы две ошибки, которые повторяются при повторной отправке того же задания: неизвестный sitekey и sitekey, не разрешённый для домена страницы, а любая другая ошибка тоже останавливает скрипт. Внутри сообщения ApiException код приходит голым текстом или в JSON-обёртке, и which_error вытаскивает его из любого варианта.
Отклонённая отправка формы получает новый токен, только если ответ содержит фразу отказа по капче вашего сайта. Используйте фразу вроде приведённой, а не голое слово captcha. Страница входа, показанная снова после неверного пароля, всё равно несёт собственные mtcaptchaConfig и mtcaptcha-verifiedtoken виджета, так что голое слово совпало бы и потратило три токена. Я видел это на своей имитации. Если проверять фразу, которая есть только в отказе, тратится одно задание.
def which_error(err):
# The message holds the code as bare text or inside a JSON envelope.
found = re.search(r"ERROR_[A-Z_]+", str(err))
return found.group(0) if found else str(err)
def log_in(username, password):
session = requests.Session()
session.headers["User-Agent"] = USER_AGENT
for attempt in range(1, 4):
page = session.get(LOGIN_URL, timeout=30) # cookies first, then config
sitekey, action = read_config(page.text)
try:
token = get_token(sitekey, action)
except ApiException as err:
code = which_error(err)
if code != "ERROR_CAPTCHA_UNSOLVABLE":
raise # a bad sitekey or domain would fail the same way again
print(f"attempt {attempt}: {code}, new task")
continue
reply = post_form(session, token, username, password)
if "Welcome" in reply.text: # use a sign your site shows on success
return reply
if "captcha check failed" not in reply.text.lower(): # your site's phrase
raise RuntimeError(f"login refused ({reply.status_code}), not the captcha")
print(f"attempt {attempt}: captcha refused ({reply.status_code}), new token")
raise RuntimeError("no login after 3 attempts")
if __name__ == "__main__":
print(log_in("alice", "YOUR_PASSWORD").text[:40])На имитации все три версии Python дали одинаковые результаты:
| Настройка имитации | Что сделал скрипт |
|---|---|
| Конфиг страницы как в документации, с action | Одно задание, in.php получил action, отправка формы принята |
| Конфиг в одну строку с callback и без action, как на демо-странице | Одно задание, поле action не отправлено, отправка формы принята |
| Страница задаёт action, но вызов его пропускает | Три задания, три отклонённые отправки формы, затем RuntimeError |
| Первые два решения заканчиваются ERROR_CAPTCHA_UNSOLVABLE | Два сообщения о повторе, затем токен третьего задания принят |
| Токену 3 секунды при отправке, срок жизни на имитации задан в 2 секунды | Отклонён как просроченный, затем принят новый токен |
| Ошибка неизвестного sitekey или домена при опросе | ApiException после одного задания и без отправки формы, в виде JSON или голого текста |
| Неверный пароль с обычным текстом отказа или отправка формы без заголовка Referer | RuntimeError после одного задания, без нового токена |
| Страница входа показана снова после неверного пароля, проверка по голому слову captcha | Три задания, затем RuntimeError. С проверкой по фразе одно задание |
Читайте таблицу как проверку моей имитации, а не какого-либо настоящего сайта. Одноразовость, короткий срок жизни и совпадение action следуют документации, но срок жизни в две секунды я выбрал произвольно.
Частые ошибки
Большинство этих ошибок приходит от CapSkip и описано в разделе Документация API MTCaptcha, кроме случаев, когда в строке сказано, что я видел ошибку сам.
| Ошибка | Причина | Исправить |
|---|---|---|
| ValidationException | SDK отклонил вызов до отправки по одной из причин из шага 2 | Сообщение называет проблему, поэтому исправьте этот аргумент |
| ERROR_RECAPTCHA_INVALID_SITEKEY | MTCaptcha не распознаёт sitekey | Скопируйте его из mtcaptchaConfig заново. Повторная отправка не помогла бы, поэтому скрипт выбрасывает исключение |
| ERROR_RECAPTCHA_INVALID_DOMAIN | Sitekey не разрешён для домена отправленного адреса | Используйте адрес страницы, на которой виджет действительно находится |
| ERROR_CAPTCHA_UNSOLVABLE | MTCaptcha не пройдена | Отправьте новое задание, что скрипт делает за вас до трёх раз |
| ERROR_TASK_NOT_SUPPORTED | CapSkip старше выпуска, в котором появилась MTCaptcha | Установите CapSkip 4.3.0 или более поздний выпуск |
| ERROR_WRONG_USERAGENT | В актуальной документации API она указана для User-Agent, который нельзя использовать для задания. Настоящее приложение не видело параметра userAgent из моего кода | Уберите параметр userAgent из get_token |
| ERROR_WRONG_USER_KEY или ERROR_KEY_DOES_NOT_EXIST | Включена API Key Validation, а ключ неверен. Вызов без apiKey уходит с ключом capskip | Передайте в CapSkip() свой настоящий ключ как apiKey |
| TimeoutException | Токен не пришёл за defaultTimeout, 120 секунд, если вы его не меняли | Посмотрите задание в Monitor CapSkip, затем запустите скрипт снова |
| NetworkException | При отправке задания на этом хосте и порту никто не отвечает, либо ответом была ошибка HTTP. Если CapSkip перестаёт отвечать во время опроса, вы получите TimeoutException | Запустите CapSkip и убедитесь, что хост и порт совпадают с его настройками подключения |
| Сайт отклоняет токен, который выглядит верным | Токен уже использовался, был слишком старым, не содержал action страницы или пришёл без Referer | Отправляйте каждый токен один раз и сразу, со страницей в качестве Referer и с собственным action страницы |
FAQ
Может ли скрипт работать на другой машине, чем CapSkip?
Да, через режим Server. Включите его в настройках подключения на ПК с CapSkip и передайте адрес этого ПК как host в CapSkip(). Больше ничего не меняется. Режиму Server нужно, чтобы CapSkip был запущен от имени администратора, а руководство по настройке рекомендует статический публичный IP. При запуске режима Server CapSkip открывает свой порт для всех адресов, поэтому добавьте блокирующее правило Windows Firewall для машин, которые не должны до него добираться. Решатель остаётся на вашем собственном оборудовании с Windows, и никакого счётчика нет.
Работает ли скрипт с невидимыми виджетами MTCaptcha?
На странице CapSkip для MTCaptcha сказано, что невидимый виджет проходит тем же запросом, что и видимый, и возвращает токен того же вида. В разделе MTCaptcha документации API невидимый режим не упомянут, и я ничего не запускал против невидимого виджета, поэтому считайте это неподтверждённым. Ваша страница всё равно должна нести sitekey в своём исходном коде, потому что read_config нуждается в нём там.
Нужен ли прокси для MTCaptcha?
Для начала нет. В документации один адрес назван годным для тестов, но сказано, что постоянное решение с одного адреса провоцирует ограничение частоты запросов. Для больших объёмов загрузите список прокси в настройках MTCaptcha в приложении или передайте параметр proxy в mtcaptcha(), например proxy={"type": "HTTP", "uri": "login:password@IP:PORT"}. Имитация получила прокси и его тип; настоящий прокси я не использовал.
Коротко
MTCaptcha на Python сводится к трём действиям: прочитать sitekey и action со страницы, запросить токен непосредственно перед отправкой формы и запросить новый, когда форма отклонена. Поскольку вы сами запускаете локальный сервис распознавания капчи CapSkip, отклонённый токен никогда не увеличивает счёт. На странице сервиса распознавания капчи для Python перечислены вызовы SDK для других типов, а в демо MTCaptcha можно проверить токен в настоящей форме.
