Перейти к основному содержимому
Возникают проблемы с получением токена?
Свяжитесь с поддержкой

MCP

Model Context Protocol (MCP) позволяет AI-агентам подключаться к внешним инструментам и сервисам.

CapMonster Cloud MCP предоставляет агенту инструменты для работы с CAPTCHA.

Как работает MCP CapMonster Cloud

С помощью MCP AI-агент может определять тип CAPTCHA и параметры задачи, обращаться к документации CapMonster Cloud, создавать задачи и получать результаты решения. При этом конечная цель работы агента – не только решить CAPTCHA, но и корректно интегрировать этот процесс в проект пользователя.

Для работы с веб-страницей MCP CapMonster Cloud можно использовать вместе с браузерным MCP capmonster-mcp-patchright:

AI-агент
├── capmonster → CapMonster Cloud API
└── patchright → браузер

capmonster отвечает за работу с CapMonster Cloud. patchright открывает страницу, помогает определить тип CAPTCHA и получить её параметры, а также применить готовое решение. Затем агент переносит проверенный сценарий в код проекта.

Типовой процесс, под который разработан SKILL.md:

  1. Получить URL целевой страницы.

  2. Определить тип CAPTCHA.

  3. Изучить документацию и определить обязательные параметры.

  4. Получить параметры со страницы.

  5. Отправить запрос в CapMonster Cloud.

  6. Получить результат.

  7. Применить результат на странице и интегрировать этот сценарий в код пользователя.

Примечание

Используйте автоматизацию только на ресурсах, где у вас есть разрешение на такие действия: например, на собственном сайте, тестовом стенде или демонстрационной странице.

Быстрый старт​

Скопируйте prompt для AI-агента

Выберите prompt в соответствии со своим окружением – Python / PyPI или TypeScript / npm – и нажмите Скопировать prompt. Затем вставьте его в Claude Code, Codex или другой AI-агент. Агент определит клиент и операционную систему, настроит capmonster и patchright, а затем проверит их работу.

Если автоматическая настройка не удалась, настройте MCP вручную по инструкции.

После проверки передайте агенту URL целевой страницы, файлы проекта и условия появления CAPTCHA. Агент должен не только проверить решение в браузере, но и интегрировать рабочий сценарий CapMonster Cloud в ваш код.

Разрешения во время настройки

Агент может запросить разрешение на установку зависимостей, изменение MCP-конфигурации, запуск команд, сетевой доступ или работу браузера. Просматривайте запросы и подтверждайте ожидаемые действия кнопкой Allow или Approve.

В Codex текущий режим разрешений можно проверить или изменить командой /permissions.

Повторно отправлять prompt перед каждой задачей не требуется. В рамках текущей сессии после загрузки SKILL.md можно передавать новые URL, условия появления CAPTCHA и задачи по интеграции.

Ручная настройка​

Работать с агентом можно через Desktop-приложение, терминал, IDE или редактор кода. Для полного сценария рекомендуется подключить оба сервера: capmonster и patchright.

Выберите способ работы – CLI-агент или Desktop-приложение. В каждой вкладке приведена полная последовательность настройки.

Шаг 1. Установите AI-агент


Для работы потребуется AI-агент или другое приложение с поддержкой MCP.

Если агент уже установлен, проверьте, что он запускается и доступен в системе.

Например, для Claude Code:

claude --version

Для Codex:

codex --version

Если команда не найдена, установите выбранный AI-агент согласно его официальной инструкции: для Claude Code, для Codex.

После установки убедитесь, что агент запускается и поддерживает подключение локальных MCP-серверов.

Агент не найден после установки

Если терминал или IDE не видит установленный агент, полностью закройте и снова откройте терминал и среду разработки. Уже запущенные приложения могут использовать старое значение PATH и не видеть новую команду до перезапуска.

Шаг 2. Установите Node.js и при необходимости uv


Для запуска MCP-серверов потребуются npx и, в зависимости от выбранной реализации CapMonster MCP, uvx.

Node.js и npx

Важно:

patchright запускается через npx, поэтому Node.js необходим независимо от выбранной реализации CapMonster MCP.

Проверьте установку:

node --version
npm --version
npx --version

Если команды недоступны, установите Node.js.

npm и npx обычно устанавливаются вместе с Node.js, поэтому отдельно устанавливать npx не требуется.

Для работы рекомендуется использовать Node.js 18 или новее.

uv и uvx

Если вы планируете использовать Python/PyPI-версию capmonster-mcp, также потребуется uvx.

Проверьте его наличие:

uvx --version

Если команда недоступна, установите uv.

После установки uv команда uvx также станет доступна.

Проверьте:

uv --version
uvx --version
Примечание

Если вы используете TypeScript/npm-версию capmonster-mcp, uv и uvx устанавливать не требуется.

Шаг 3. Получите API-ключ


Для работы capmonster необходим API-ключ CapMonster Cloud.

Он передаётся MCP-серверу через переменную окружения:

CM_API_KEY
Шаг 4. Выберите реализацию CapMonster MCP


Доступны две эквивалентные реализации capmonster-mcp.

Для этой версии используется npm-пакет capmonster-mcp и npx.

MCP-сервер запускается командой:

npx -y capmonster-mcp

Устанавливать capmonster-mcp как зависимость вашего проекта не требуется. По умолчанию MCP-клиент может запускать опубликованный пакет напрямую через npx или uvx.

Установка пакетов через npm и pip


По умолчанию предварительно устанавливать MCP-пакеты не требуется: их можно запускать напрямую через npx или uvx. Если вы хотите установить пакеты заранее, используйте один из вариантов ниже.

CapMonster Cloud MCP

Установите capmonster-mcp через npm:

npm i capmonster-mcp

Проверить установку можно командой:

npm list capmonster-mcp

После установки для запуска capmonster используйте npx:

{
  "command": "npx",
  "args": ["capmonster-mcp"],
  "env": {
    "CM_API_KEY": "YOUR_API_KEY"
  }
}

Patchright MCP

Если вы планируете использовать браузер для открытия страниц, получения параметров CAPTCHA и применения решения, установите capmonster-mcp-patchright. Исходный код доступен в официальном репозитории:

npm i capmonster-mcp-patchright

Проверить установку можно командой:

npm list capmonster-mcp-patchright

Предварительная установка capmonster-mcp-patchright необязательна. Во всех примерах ниже его также можно запускать напрямую через:

npx -y capmonster-mcp-patchright

После установки npm-пакета или Python-пакета полностью перезапустите MCP-клиент, если установка выполнялась после его запуска.


Шаг 5. Настройте MCP-клиент


Выберите используемый CLI-клиент.

Для общей проектной конфигурации создайте в корне проекта файл .mcp.json и добавьте в него capmonster и patchright.

подсказка

Это не единственное возможное расположение. Claude Code поддерживает разные области конфигурации; настройки конкретного пользователя или проекта могут также храниться в .claude.json или добавляться командами самого клиента. Если MCP настраивает агент, разрешите ему определить подходящий scope и файл автоматически.

{
  "mcpServers": {
    "capmonster": {
      "command": "npx",
      "args": ["-y", "capmonster-mcp"],
      "env": {
        "CM_API_KEY": "YOUR_API_KEY"
      }
    },
    "patchright": {
      "command": "npx",
      "args": ["-y", "capmonster-mcp-patchright"]
    }
  }
}

После перезапуска Claude Code проверьте подключение командой /mcp.

Замените YOUR_API_KEY на API-ключ CapMonster Cloud и перезапустите MCP-клиент.

Шаг 6. Передайте агенту prompt


Откройте новый чат или сессию и отправьте prompt из блока Быстрый старт. После проверки передайте URL страницы, файлы проекта и условия появления CAPTCHA.

Во время настройки подтверждайте только ожидаемые запросы на разрешения. В рамках текущей сессии повторно отправлять prompt перед каждой задачей не требуется.

Доступные инструменты​

После подключения MCP-серверов инструменты становятся доступны AI-агенту автоматически. Вручную выбирать их обычно не требуется – агент вызывает нужные инструменты в зависимости от текущей задачи.

CapMonster Cloud​

capmonster-mcp предоставляет следующие инструменты:

  • get_supported_tasks – возвращает поддерживаемые типы задач CapMonster Cloud;
  • get_task_parameters(task_type) – возвращает параметры выбранного типа задачи и схему решения;
  • get_docs(url, offset, limit, section) – загружает документацию CapMonster Cloud;
  • create_task(task) – создаёт задачу и возвращает taskId;
  • get_task_result(task_id) – однократно проверяет статус задачи;
  • get_task_result_wait(task_id, timeout_seconds, poll_interval_seconds) – ожидает завершения задачи автоматически;
  • get_actual_user_agent() – возвращает актуальный Windows User-Agent;
  • get_balance() – возвращает баланс аккаунта CapMonster Cloud.

Patchright​

capmonster-mcp-patchright предоставляет инструменты для работы с браузером. Агент получает доступ к ним через MCP-клиент и самостоятельно выбирает нужные действия.

Актуальный список инструментов доступен в официальном репозитории и на странице npm-пакета capmonster-mcp-patchright.

Устранение неполадок​

Поручите диагностику агенту

Если настройка не работает, передайте агенту текст ошибки. Он может проверить runtime, команды запуска, MCP-конфигурации пользователя и проекта, а также предложить или выполнить необходимые исправления.

MCP-сервер не запускается

Проверьте, что команда из конфигурации доступна в том же окружении, из которого запускается MCP-клиент:

node --version
npx --version
npx -y capmonster-mcp

Если команда запускается и остаётся без вывода, это не обязательно ошибка: STDIO MCP-сервер ожидает подключения клиента. Остановить тестовый запуск можно сочетанием клавиш Ctrl+C.

Также проверьте, что:

  • в JSON-конфигурации нет комментариев, лишних запятых и незакрытых скобок;

  • имена полей mcpServers, command, args и env указаны без ошибок;

  • после изменения конфигурации MCP-клиент полностью перезапущен;

  • загрузка пакета через npx или uvx не блокируется сетью, прокси, антивирусом или корпоративной политикой.

Команда capmonster-mcp не найдена после установки пакета

Предварительно установленная CLI-команда должна быть доступна в PATH процесса, из которого запускается MCP-клиент.

Проверьте расположение команды:

where.exe capmonster-mcp

Если терминал находит команду, а Desktop-приложение – нет, полностью закройте и снова откройте приложение. При необходимости укажите в поле command полный путь к исполняемому файлу.

Инструменты capmonster или patchright не отображаются

Попросите агента проверить, откуда текущая сессия загружает MCP-конфигурацию. Расположение зависит от клиента, области действия и способа подключения сервера:

  • в Claude Code серверы могут быть настроены на уровне проекта или пользователя; конфигурация может находиться в .mcp.json, .claude.json или управляться командами Claude Code;

  • Claude Desktop использует claude_desktop_config.json;

  • Codex использует ~/.codex/config.toml, %USERPROFILE%\.codex\config.toml или проектный .codex/config.toml;

  • в ChatGPT Desktop локальные серверы также можно добавить через настройки MCP.

После исправления конфигурации полностью перезапустите клиент и откройте новую сессию. В Claude Code подключение можно проверить через /mcp, а в Codex – через /mcp или codex mcp list.

get_balance возвращает ошибку

Попросите агента проверить конфигурацию capmonster. Обычно нужно убедиться, что:

  • в переменной CM_API_KEY указан действующий API-ключ CapMonster Cloud;

  • вместо ключа не осталось значение YOUR_API_KEY;

  • ключ передан в блоке env сервера capmonster, а не patchright.

После изменения ключа перезапустите MCP-клиент. Агент сможет повторно проверить подключение и баланс.

Если баланс равен нулю, пополните его перед созданием задач.

get_docs не загружает документацию

Попросите агента проверить сетевой доступ MCP-клиента к https://docs.capmonster.cloud/ и загрузку файла:

https://docs.capmonster.cloud/llms.txt

Если документация временно недоступна или требуется дополнительно проверить параметры задачи, агент может использовать спецификацию API:

https://api.capmonster.cloud/docs/swagger-ui/spec.js
patchright не открывает страницу

Проверьте работу node, npx и команды запуска:

npx -y capmonster-mcp-patchright

Если странице требуются прокси, User-Agent или locale, передайте эти параметры агенту. Он сможет использовать их при запуске браузера через patchright.

Задача возвращает ошибку или сайт отклоняет решение

Передайте агенту текст ошибки и условия появления CAPTCHA. Для диагностики он может:

  1. проверить поддерживаемый тип задачи;

  2. получить актуальные параметры и схему решения;

  3. открыть документацию для выбранного типа CAPTCHA;

  4. повторно получить динамические параметры после перезагрузки или повторного вызова CAPTCHA;

  5. проверить согласованность User-Agent, прокси, cookies, заголовков и Client Hints для CAPTCHA, привязанных к сессии;

  6. убедиться, что результат применяется в формате, предусмотренном для конкретного типа CAPTCHA.

Не используйте устаревшие challenge, token, data, blob и другие одноразовые параметры.

ERROR_INVALID_TASK обычно указывает на некорректные или устаревшие параметры. ERROR_CAPTCHA_UNSOLVABLE может быть временной ошибкой – агент может проверить входные данные и создать новую задачу.

Часто задаваемые вопросы​

Нужно ли вручную выбирать и вызывать MCP-инструменты?

Нет. После подключения MCP-серверов инструменты автоматически становятся доступны AI-агенту. Агент сам выбирает и вызывает их в зависимости от текущей задачи.

Обязательно ли подключать оба MCP-сервера?

Нет. capmonster можно использовать отдельно, если параметры CAPTCHA уже известны и работа с браузером не требуется. patchright нужен, когда агенту необходимо открыть страницу, получить параметры CAPTCHA или применить результат решения.

Какую реализацию выбрать: npm или Python?

Обе реализации capmonster-mcp предоставляют одинаковые инструменты. Выберите вариант под своё окружение:

  • npm – если уже установлены Node.js и npx;

  • Python – если используется Python 3.11 или новее и установлен uvx.

Для patchright в любом случае необходимы Node.js и npx.

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

Передавайте API-ключ через переменную окружения CM_API_KEY в конфигурации сервера capmonster. Не добавляйте его в prompt, сообщения чата, примеры кода или публичный репозиторий.

Если конфигурационный файл содержит реальный ключ, исключите его из Git или используйте безопасное хранилище секретов, поддерживаемое MCP-клиентом.

Нужно ли отправлять prompt перед каждой CAPTCHA?

Нет. В рамках текущей сессии после настройки достаточно передавать новые URL, условия появления CAPTCHA и задачи по интеграции.

В новой сессии prompt рекомендуется отправить снова, если агент не сохраняет загруженные инструкции и результаты проверки окружения.

Как проверить, какие типы CAPTCHA поддерживаются?

Попросите агента определить поддерживаемые типы CAPTCHA. Для этого он может использовать get_supported_tasks, а для конкретной задачи – get_task_parameters(task_type) и документацию через get_docs.

Нужно ли настраивать прокси в MCP-конфигурации?

Не обязательно. Если браузеру требуется прокси, передайте его параметры агенту – он сможет использовать их при запуске браузера без изменения MCP-конфигурации.

Если выбранный тип CAPTCHA требует собственного прокси, агент также должен передать его параметры в задаче CapMonster Cloud. Для CAPTCHA, привязанных к IP-адресу или сессии, в браузере и задаче должен использоваться один и тот же прокси.

Статья была полезной?
Узнайте стоимость AI решения КАПЧ