Metadata-Version: 2.4
Name: capguru-mcp
Version: 0.2.0
Summary: MCP server for the Cap.Guru captcha solving service: lets AI assistants open pages and solve reCAPTCHA v2/v3, Cloudflare Turnstile, text captchas, hCaptcha, GeeTest, FunCaptcha, TikTok, AWS WAF and Yandex SmartCaptcha
Author: Cap.Guru
Project-URL: Homepage, https://cap.guru
Project-URL: Documentation, https://docs.cap.guru
Keywords: mcp,captcha,solver,playwright,cap.guru,claude,cursor,turnstile,recaptcha
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.2
Requires-Dist: capguru>=0.4.0
Requires-Dist: playwright>=1.40

# capguru-mcp

**English** | [Русский](#русский)

MCP server for the [Cap.Guru](https://cap.guru) captcha solving service.
It lets AI assistants (Claude Desktop, Claude Code, Cursor and other MCP clients) open web pages in a browser and solve captchas on them.

Supported: reCAPTCHA v2/v3, Cloudflare Turnstile, text (image) captchas, hCaptcha, GeeTest v3/v4, FunCaptcha (Arkose Labs), TikTok, AWS WAF, Yandex SmartCaptcha.

## Installation

```
pip install capguru-mcp
playwright install chromium
```

## Connecting to an MCP client

Claude Desktop (`claude_desktop_config.json`), Cursor (`.cursor/mcp.json`) and most other clients:

```json
{
  "mcpServers": {
    "capguru": {
      "command": "capguru-mcp",
      "env": {
        "CAPGURU_API_KEY": "YOUR_KEY"
      }
    }
  }
}
```

Claude Code:

```
claude mcp add capguru --env CAPGURU_API_KEY=YOUR_KEY -- capguru-mcp
```

Without installing (via [uv](https://docs.astral.sh/uv/)): use `"command": "uvx", "args": ["capguru-mcp"]`.

## Tools

| Tool | Description |
|---|---|
| `open_browser` | Launch a browser (`headless`, `channel`: `chrome`/`msedge`, `proxy`) |
| `connect_browser` | Connect to a running Chrome started with `--remote-debugging-port` |
| `goto` | Open a URL |
| `click`, `fill` | Click an element, type text into an input |
| `screenshot` | Screenshot of the page |
| `page_info` | Current URL and title |
| `detect_captcha` | Detect the captcha type without solving |
| `solve_captcha` | Solve the captcha: `auto` or a specific type |
| `solve_recaptcha_token` | Get a reCAPTCHA v2 / v2 Invisible / v3 token (`sitekey`, `pageurl`, `version`, `min_score`); works without a browser too |
| `solve_turnstile_token` | Get a Cloudflare Turnstile token (`sitekey`, `pageurl`); works without a browser too |
| `solve_image_captcha` | Recognize a text captcha from an image: element `selector`, `image_base64`, `image_path` or `image_url`; optional `vernet`, `fill_selector` |
| `close_browser` | Close the browser |

Example requests to the assistant:

- *"Open https://site.com/login, solve the captcha and take a screenshot."*
- *"Get a reCAPTCHA token for sitekey 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ- on https://www.google.com/recaptcha/api2/demo."*
- *"Get a reCAPTCHA v3 token for sitekey 6Ldb4ccaAAAAACMxv8uxUIMckZy1og98rs_h3AmO on http://learn.captcha.guru/ln/recap3/."*
- *"Open https://react-turnstile.vercel.app/basic and solve the Turnstile."*
- *"Recognize the captcha image #captcha_img and type the answer into #captcha_input."*

`solve_recaptcha_token` uses the Cap.Guru token method (`userrecaptcha`): it returns the `g-recaptcha-response` token. If a page is open, the sitekey, URL and User-Agent are taken from it; for v2 the token is inserted into the page and the site callback is called. For v3 pass `version: v3` (optionally `min_score`, service default 0.1); the token is only returned, because v3 sites request it themselves.

`solve_turnstile_token` works the same way for Cloudflare Turnstile (`method=turnstile`): with an open page the token is put into `cf-turnstile-response` and the Turnstile callback is called. Typical solve time is 10–30 seconds.

## Settings (environment variables)

| Variable | Default | Description |
|---|---|---|
| `CAPGURU_API_KEY` | — | Cap.Guru API key (required) |
| `CAPGURU_SERVER` | `https://api.cap.guru` | API server |
| `CAPGURU_ATTEMPTS` | `5` | Max number of solving attempts |
| `CAPGURU_DEBUG` | `1` | Include the solver log in tool results |
| `CAPGURU_BROWSER_CHANNEL` | — | `chrome` or `msedge` to use an installed browser |
| `CAPGURU_BROWSER_PATH` | — | Path to a browser executable |
| `CAPGURU_BROWSER_ARGS` | — | Extra browser arguments, space separated |

Full documentation: https://docs.cap.guru

---

## Русский

MCP-сервер для сервиса решения капчи [Cap.Guru](https://cap.guru).
Позволяет ИИ-ассистентам (Claude Desktop, Claude Code, Cursor и другим MCP-клиентам) открывать страницы в браузере и решать на них капчу.

Поддерживаются: reCAPTCHA v2/v3, Cloudflare Turnstile, текстовые капчи (картинкой), hCaptcha, GeeTest v3/v4, FunCaptcha (Arkose Labs), TikTok, AWS WAF, Яндекс SmartCaptcha.

### Установка

```
pip install capguru-mcp
playwright install chromium
```

### Подключение к MCP-клиенту

Claude Desktop (`claude_desktop_config.json`), Cursor (`.cursor/mcp.json`) и большинство других клиентов:

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

Claude Code:

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

Без установки (через [uv](https://docs.astral.sh/uv/)): `"command": "uvx", "args": ["capguru-mcp"]`.

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

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

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

- *«Открой 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_recaptcha_token` использует токенный метод Cap.Guru (`userrecaptcha`) и возвращает токен `g-recaptcha-response`. Если страница открыта, sitekey, адрес и User-Agent берутся с неё; для v2 токен вставляется на страницу и вызывается callback сайта. Для v3 укажите `version: v3` (и при необходимости `min_score`, по умолчанию у сервиса 0.1); токен только возвращается, потому что сайты с v3 запрашивают его сами.

`solve_turnstile_token` так же работает для Cloudflare Turnstile (`method=turnstile`): если страница открыта, токен вставляется в `cf-turnstile-response` и вызывается callback Turnstile. Обычное время решения — 10–30 секунд.

### Настройки (переменные окружения)

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

Полная документация: https://docs.cap.guru
