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

logo

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

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

Версия	Изменения	Скачать
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

json

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

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

Claude Code

bash

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

Cursor

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

json

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

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.

json

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

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

Visual Studio

Файл %USERPROFILE%\.mcp.json или .mcp.json в папке решения. Формат как у VS Code. Инструменты доступны в режиме Agent чата GitHub Copilot.

Cline и Roo Code

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

Continue

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

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:

json

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

Gemini CLI

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

OpenAI Codex CLI

Файл ~/.codex/config.toml. Codex использует формат TOML:

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 и переменную CAPGURU_API_KEY.

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

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

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

Если установлен uv, сервер можно запускать без pip install: "command": "uvx", "args": ["capguru-mcp"]

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

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

Примеры запросов:

«Открой https://site.com/login, реши капчу и сделай скриншот»
«Зайди на сайт, заполни форму регистрации и пройди капчу»
«Получи токен reCAPTCHA для sitekey 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ- на https://www.google.com/recaptcha/api2/demo»
«Получи токен reCAPTCHA v3 для sitekey 6Ldb4ccaAAAAACMxv8uxUIMckZy1og98rs_h3AmO на http://learn.captcha.guru/ln/recap3/»
«Открой https://react-turnstile.vercel.app/basic и реши Turnstile»
«Распознай капчу с картинки #captcha_img и введи ответ в #captcha_input»

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

Инструмент solve_captcha решает капчу прямо на открытой странице: кликает по картинкам, двигает ползунки, проходит многошаговые задания.
В режиме auto сервер сам определяет тип капчи и ждёт её появления. Поддерживаются reCAPTCHA v2, hCaptcha, GeeTest v3 и v4, FunCaptcha (Arkose Labs), TikTok, AWS WAF и Other.

Токены reCAPTCHA и Cloudflare Turnstile

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

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

Инструмент solve_image_captcha распознаёт капчу с картинки: элемента на странице, файла, адреса или base64.
Через параметр vernet можно указать тип капчи (Яндекс, ВКонтакте, арифметическая и другие), а через fill_selector — поле, в которое ввести ответ.

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

Браузер:

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

Капча:

Инструмент	Описание
`detect_captcha`	Определить тип капчи на странице, не решая
`solve_captcha`	Решить капчу на странице: `auto` или конкретный тип
`solve_recaptcha_token`	Получить токен reCAPTCHA v2 / v2 Invisible / v3 (`sitekey`, `pageurl`, `version`, `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`	—	Дополнительные аргументы браузера через пробел

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

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

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

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

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

Любые клиенты с поддержкой 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 сервер не требует программирования: им управляет ИИ-ассистент по текстовым командам.

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

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

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

Установка ​

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

Claude Desktop ​

Claude Code ​

Cursor ​

Windsurf ​

VS Code (GitHub Copilot) ​

Visual Studio ​

Cline и Roo Code ​

Continue ​

Zed ​

Gemini CLI ​

OpenAI Codex CLI ​

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

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

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

Токены reCAPTCHA и Cloudflare Turnstile ​

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

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

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

Параметры: ​

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

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

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

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

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

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

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

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

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

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

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

Установка

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

Claude Desktop

Claude Code

Cursor

Windsurf

VS Code (GitHub Copilot)

Visual Studio

Cline и Roo Code

Continue

Zed

Gemini CLI

OpenAI Codex CLI

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

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

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

Токены reCAPTCHA и Cloudflare Turnstile

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

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

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

Параметры:

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

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

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

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

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

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

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

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