MCP сервер для решения капчи

MCP сервер (capguru-mcp) подключает сервис решения капчи к ИИ-ассистентам и агентам: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code с GitHub Copilot, Cline, Zed, Gemini CLI, OpenAI Codex CLI и любым другим клиентам с поддержкой Model Context Protocol.
Ассистент сам открывает страницу в браузере, находит капчу, решает её и продолжает работу. Достаточно описать задачу обычным текстом.

Актуальная версия:

Версия	Изменения	Скачать
0.3.2	Фикс мелких багов	PyPI
0.3	Turnstile работает в браузере, action для reCAPTCHA v3, v2 Invisible, новые инструменты page_text, press, list_tabs, switch_tab. API-ключ больше не попадает в логи	PyPI
0.2	Релиз	PyPI

Что такое MCP сервер

Model Context Protocol (MCP) — открытый стандарт, через который ИИ-ассистенты подключают внешние инструменты.
MCP сервер добавляет ассистенту инструменты для работы с браузером и решения капчи. Ассистент вызывает их сам, когда это нужно для задачи.

Что умеет сервер:

• Решать капчу на странице в браузере: reCAPTCHA v2, hCaptcha, GeeTest v3/v4, FunCaptcha (Arkose Labs), TikTok, AWS WAF, Other.
• Автоматически определять тип капчи на странице.
• Получать токены reCAPTCHA v2, v2 Invisible, v3 и Cloudflare Turnstile, в том числе без браузера, по sitekey и адресу страницы.
• Распознавать текстовые капчи с картинки и вводить ответ в поле.
• Открывать страницы, нажимать кнопки и клавиши, заполнять формы, читать текст страницы, переключать вкладки и делать скриншоты.
• Подключаться к уже запущенному Chrome, которым управляет другой инструмент.

Установка

Сервер опубликован на PyPI. Нужен Python 3.10 или новее.

pip install capguru-mcp
playwright install chromium

Обновление до последней версии:

pip install -U capguru-mcp

API-ключ передаётся через переменную окружения CAPGURU_API_KEY в настройках клиента. Ключ хранится только в вашем локальном конфиге и отправляется только на наш API-сервер.

Подключение к MCP-клиентам

Большинство клиентов используют одинаковый формат с ключом mcpServers. Отличаются только расположение файла и, у некоторых клиентов, название ключа.

Claude Desktop

Файл claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "capguru": {
      "command": "capguru-mcp",
      "env": { "CAPGURU_API_KEY": "ВАШ_КЛЮЧ" }
    }
  }
}

После изменения конфига перезапустите Claude Desktop.

Claude Code

claude mcp add capguru --env CAPGURU_API_KEY=ВАШ_КЛЮЧ -- capguru-mcp

Cursor

Файл ~/.cursor/mcp.json (для всех проектов) или .cursor/mcp.json в папке проекта. Формат как у Claude Desktop.

Windsurf

Файл ~/.codeium/windsurf/mcp_config.json (Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json). Формат с ключом mcpServers. После изменения перезапустите Windsurf.

VS Code (GitHub Copilot)

Файл .vscode/mcp.json в папке проекта. В VS Code ключ называется servers, а не mcpServers.

{
  "servers": {
    "capguru": {
      "type": "stdio",
      "command": "capguru-mcp",
      "env": { "CAPGURU_API_KEY": "ВАШ_КЛЮЧ" }
    }
  }
}

Инструменты MCP доступны в режиме Agent чата Copilot.

Visual Studio

Файл %USERPROFILE%\.mcp.json или .mcp.json в папке решения. Формат как у VS Code.

Cline и Roo Code

Откройте в расширении раздел MCP Servers и нажмите «Configure MCP Servers». Добавьте блок capguru в формате mcpServers.

Continue

Файл ~/.continue/config.yaml:

mcpServers:
  - name: capguru
    command: capguru-mcp
    env:
      CAPGURU_API_KEY: ВАШ_КЛЮЧ

Zed

Файл настроек Zed settings.json (Linux: ~/.config/zed/settings.json, Windows: %APPDATA%\Zed\settings.json). В Zed ключ называется context_servers:

{
  "context_servers": {
    "capguru": {
      "command": "capguru-mcp",
      "args": [],
      "env": { "CAPGURU_API_KEY": "ВАШ_КЛЮЧ" }
    }
  }
}

Gemini CLI

Файл ~/.gemini/settings.json (для всех проектов) или .gemini/settings.json в папке проекта. Формат mcpServers.

OpenAI Codex CLI

Файл ~/.codex/config.toml:

[mcp_servers.capguru]
command = "capguru-mcp"
env = { CAPGURU_API_KEY = "ВАШ_КЛЮЧ" }

Другие клиенты

Amazon Q Developer CLI (~/.aws/amazonq/mcp.json), GitHub Copilot CLI (~/.copilot/mcp-config.json), Google Antigravity и другие MCP-клиенты используют тот же формат mcpServers.

Если клиент не находит команду capguru-mcp

На Windows папка Scripts от Python может быть не прописана в PATH. Запустите сервер через Python: "command": "python", "args": ["-m", "capguru_mcp"] или укажите полный путь к capguru-mcp.

Запуск без установки через uv

"command": "uvx", "args": ["capguru-mcp"]

Как использовать

После подключения просто опишите ассистенту задачу. Примеры запросов:

• Открой https://site.com/login, реши капчу и сделай скриншот
• Зайди на сайт, заполни форму регистрации и пройди капчу
• Получи токен reCAPTCHA для sitekey 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ- на https://www.google.com/recaptcha/api2/demo
• Получи токен reCAPTCHA v3 с action verife для sitekey 6LdSQV8mAAAAAA8tgiox2isjB1H4QSr-pNBXajUT на https://test.cap.guru/demo/recap
• Открой https://test.cap.guru/demo/cloud и реши Turnstile
• Распознай капчу с картинки #captcha_img и введи ответ в #captcha_input

Решение капчи в браузере

Инструмент solve_captcha решает капчу прямо на открытой странице: кликает по картинкам, двигает ползунки, проходит многошаговые задания.
В режиме auto сервер сам определяет тип капчи и ждёт её появления. Если указан конкретный тип, сервер сначала проверяет, что эта капча есть на странице.
Решение кликами может занять несколько минут. Сервер каждые 10 секунд отправляет уведомление о ходе работы, чтобы клиенты с таймаутом на вызов не обрывали запрос.

Токены reCAPTCHA и Cloudflare Turnstile

Инструменты solve_recaptcha_token и solve_turnstile_token получают готовый токен от сервиса, без решения картинок в браузере.
Без браузера достаточно sitekey и адреса страницы: токен вернётся текстом, и его можно использовать в своих запросах.
Если страница открыта, sitekey, адрес, режим Invisible и action для v3 берутся с неё. Токен reCAPTCHA v2 или Turnstile вставляется на страницу, и вызывается callback сайта.
Для reCAPTCHA v3 передайте action, который использует сайт: сайты проверяют его вместе с оценкой.

Распознавание текстовой капчи

Инструмент solve_image_captcha распознаёт капчу с картинки: элемента на странице, файла с изображением, адреса или base64.
vernet задаёт тип капчи. По умолчанию он не передаётся, и тип выбирает сервис. Если капча с известного сайта, укажите её тип:

vernet	Тип
2	General v1
6	General v2
22	Арифметика
12	Rambler
18	General Yandex
20	Yandex, 6 символов
16	ВКонтакте
14	SolveMedia
13	ГИБДД
9	Одноклассники
17	World of Tanks
5	Microsoft Hotmail

Для искажённого текста без известного сайта попробуйте 2 или 6.
Для арифметики (vernet 22) сервис возвращает выражение как есть, например 27+15=, а MCP сервер сам вычисляет ответ и вводит его в поле.
fill_selector вводит ответ в поле.

Инструменты:

Браузер:

Инструмент	Описание
open_browser	Запустить браузер (headless, channel: chrome / msedge, proxy)
connect_browser	Подключиться к запущенному Chrome с --remote-debugging-port
goto	Открыть адрес
click, fill, press	Нажать на элемент, ввести текст в поле, нажать клавишу
page_text	Видимый текст страницы или элемента
list_tabs, switch_tab	Список вкладок и переключение активной
screenshot	Скриншот страницы
page_info	Текущий адрес и заголовок
close_browser	Закрыть браузер

Капча:

Инструмент	Описание
detect_captcha	Определить тип капчи на странице, не решая
solve_captcha	Решить капчу на странице: auto или конкретный тип (other для Яндекс SmartCaptcha)
solve_recaptcha_token	Токен reCAPTCHA: v2, v2 Invisible (invisible), v3 (action, min_score)
solve_turnstile_token	Токен Cloudflare Turnstile (sitekey, pageurl)
solve_image_captcha	Текстовая капча с картинки (selector, image_base64, image_path или image_url; vernet, fill_selector)

Поддержка капч:

reCaptcha2	reCaptcha3	Turnstile	FunCaptcha	TikTok	GeeTest	AWS WAF	hCaptcha	Текстовые	Other
Да	Да	Да	Да	Да	Да	Да	Да	Да	Да

Параметры:

Задаются переменными окружения в блоке env конфига клиента.

Переменная	По умолчанию	Описание
CAPGURU_API_KEY	—	API-ключ (обязательно)
CAPGURU_SERVER	https://api.cap.guru	Сервер API
CAPGURU_ATTEMPTS	5	Макс. количество попыток
CAPGURU_DEBUG	1	Добавлять лог решения в ответ ассистенту
CAPGURU_BROWSER_CHANNEL	—	chrome или msedge, чтобы использовать установленный браузер
CAPGURU_BROWSER_PATH	—	Путь к исполняемому файлу браузера
CAPGURU_BROWSER_ARGS	—	Дополнительные аргументы браузера через пробел

Формат прокси одинаковый во всех инструментах: http://логин:пароль@хост:порт, socks5://... или логин:пароль@хост:порт.

Обработка ошибок

Ошибки возвращаются ассистенту как ошибки инструмента с понятным текстом:

Сообщение	Причина
Cap.Guru account error (API key or balance)	Неверный API-ключ или нулевой баланс
Not solved: ...	Капчу не удалось решить за все попытки
No captcha found on the page within 30 s	На странице не появилась капча
Captcha "recaptcha2" not found on the page within 30 s	Запрошенного типа капчи на странице нет
No browser page. Call open_browser or connect_browser first.	Браузер ещё не открыт
CAPGURU_API_KEY environment variable is not set	В конфиге клиента не указан ключ
Could not download the image: HTTP 404	По image_url не пришла картинка

Безопасность

image_path принимает только файлы изображений (png, jpg, gif, bmp, webp) до 5 МБ и проверяет их содержимое. image_url скачивается без cookies браузера, если не указан use_page_cookies. Другие локальные файлы сервер не отправляет.

Частые вопросы

Какие ИИ-ассистенты поддерживаются?

Любые клиенты с поддержкой Model Context Protocol: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code и Visual Studio с GitHub Copilot, Cline, Roo Code, Continue, Zed, Gemini CLI, OpenAI Codex CLI, Amazon Q Developer CLI и другие.

Нужен ли браузер для решения капчи?

Для решения капчи на странице — да: сервер запускает Chromium или установленный Chrome / Edge.
Токены reCAPTCHA и Cloudflare Turnstile можно получить без браузера: достаточно sitekey и адреса страницы.

Можно ли решать капчу в браузере, которым управляет другой MCP сервер?

Да. Запустите Chrome с параметром --remote-debugging-port=9222 и попросите ассистента подключиться через connect_browser.

Работает ли сервер через прокси?

Да. Передайте прокси в open_browser или в инструменты токенов в формате http://логин:пароль@хост:порт.

Где хранится API-ключ?

Только в конфиге вашего MCP-клиента на вашем компьютере. Сервер отправляет ключ только на наш API.

Чем MCP сервер отличается от Python и Node.js модулей?

Модули подключаются в код ваших скриптов. MCP сервер не требует программирования: им управляет ИИ-ассистент по текстовым командам.