<!-- mcp-name: guru.cap/capguru-mcp -->

<p align="center">
  <img src="https://docs.cap.guru/_images/capguru_mcp_banner.png" alt="Cap.Guru MCP Server for solving captchas" width="100%">
</p>

<p align="center">
  <b>Let AI assistants and agents solve captchas on their own.</b><br>
  reCAPTCHA v2/v3 · Cloudflare Turnstile · hCaptcha · Yandex SmartCaptcha · GeeTest v3/v4 · FunCaptcha · AWS WAF · TikTok · text captchas
</p>

<p align="center">
  <a href="https://pypi.org/project/capguru-mcp/"><img src="https://img.shields.io/pypi/v/capguru-mcp" alt="PyPI version"></a>
  <a href="https://pypi.org/project/capguru-mcp/"><img src="https://img.shields.io/pypi/pyversions/capguru-mcp" alt="Python versions"></a>
  <a href="https://registry.modelcontextprotocol.io/v0/servers?search=capguru"><img src="https://img.shields.io/badge/MCP%20Registry-guru.cap%2Fcapguru--mcp-blue" alt="MCP Registry"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/capguru-dev/capguru-mcp" alt="License"></a>
</p>

<p align="center">
  <a href="https://docs.cap.guru/en/modules/mcp.html">Documentation</a> ·
  <a href="https://docs.cap.guru/ru/modules/mcp.html">Документация на русском</a> ·
  <a href="https://cap.guru">Cap.Guru</a>
</p>

---

**capguru-mcp** is a [Model Context Protocol](https://modelcontextprotocol.io) server that connects the [Cap.Guru](https://cap.guru) captcha solving service to Claude Desktop, Claude Code, Cursor, Windsurf, VS Code (GitHub Copilot), Cline, Zed, Gemini CLI, OpenAI Codex CLI and any other MCP client.

The assistant opens a page in the browser, finds the captcha, solves it and goes on with the task. You just describe what you need in plain language.

## Features

- **Solve captchas right on the page**: clicks images, drags sliders, completes multi-step challenges.
- **Automatic detection** of the captcha type.
- **Tokens without a browser**: reCAPTCHA v2, v2 Invisible, v3 (with `action`), reCAPTCHA v3 Enterprise and Cloudflare Turnstile by sitekey and page URL.
- **Text captchas** from a page element, file, URL or base64, with the answer typed into the input.
- **Browser tools** for the agent: open pages, click, type, press keys, read page text, switch tabs, take screenshots.
- **Works with your own Chrome**: connect over CDP to a browser driven by another tool.
- **Progress notifications** during long solves, so clients with call timeouts do not drop the request.
- **Your API key stays private**: it is masked in all logs and sent only to the Cap.Guru API.

## Supported captchas

| Captcha | In the browser | Token |
|---|:---:|:---:|
| reCAPTCHA v2 / v2 Invisible | ✅ | ✅ |
| reCAPTCHA v3 | | ✅ |
| Cloudflare Turnstile | | ✅ |
| hCaptcha | ✅ | |
| Yandex SmartCaptcha | ✅ | |
| GeeTest v3 / v4 | ✅ | |
| FunCaptcha (Arkose Labs) | ✅ | |
| AWS WAF | ✅ | |
| TikTok | ✅ | |
| Text (image) captchas | ✅ | |

## Quick start

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

Add the server to your MCP client. Example for **Claude Desktop** (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), Windsurf, Gemini CLI and most other clients:

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

**Claude Code:**

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

**VS Code** (`.vscode/mcp.json`) uses the `servers` key, **Zed** uses `context_servers`, **Codex CLI** uses TOML. Ready configs for every client are in the [documentation](https://docs.cap.guru/en/modules/mcp.html).

> If the client cannot find the `capguru-mcp` command (often on Windows), use `"command": "python", "args": ["-m", "capguru_mcp"]`, or run without installing via `"command": "uvx", "args": ["capguru-mcp"]`.

## Example requests

- Open `https://site.com/login`, solve the captcha and take a screenshot
- Go to the site, fill in the sign-up form and pass the captcha
- Get a reCAPTCHA token for sitekey `6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-` on `https://www.google.com/recaptcha/api2/demo`
- Get a reCAPTCHA v3 token with action `verify` for sitekey `6LdSQV8mAAAAAA8tgiox2isjB1H4QSr-pNBXajUT` on `https://test.cap.guru/demo/recapv3`
- Open `https://test.cap.guru/demo/cloud` and solve the Turnstile
- Recognize the captcha image `#captcha_img` and type the answer into `#captcha_input`

## Tools

| Tool | Description |
|---|---|
| `open_browser` | Launch Chromium, Chrome or Edge (`headless`, `channel`, `proxy`) |
| `connect_browser` | Connect to a running Chrome started with `--remote-debugging-port` |
| `goto` | Open a URL |
| `click`, `fill`, `press` | Click an element, type into an input, press a key |
| `page_text` | Visible text of the page or an element |
| `list_tabs`, `switch_tab` | List tabs and switch the active one |
| `screenshot`, `page_info` | Screenshot, current URL and title |
| `detect_captcha` | Detect the captcha type without solving |
| `solve_captcha` | Solve the captcha on the page: `auto` or a type (`other` = Yandex SmartCaptcha) |
| `solve_recaptcha_token` | reCAPTCHA v2, v2 Invisible (`invisible`), v3 (`action`, default `verify`), v3 Enterprise (`enterprise`) token |
| `solve_turnstile_token` | Cloudflare Turnstile token |
| `solve_image_captcha` | Text captcha from an image; `vernet` sets the captcha kind, arithmetic is calculated |
| `close_browser` | Close the browser |

## Settings

| 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 |

Proxy format is the same everywhere: `http://login:password@host:port`, `socks5://...` or `login:password@host:port`.

## Security

- The API key is masked in logs and error messages and is sent only to the Cap.Guru API.
- `image_path` accepts only image files (png, jpg, gif, bmp, webp) up to 5 MB.
- `image_url` is downloaded without browser cookies unless `use_page_cookies` is set.

## Requirements

Python 3.10+, Playwright (installed automatically, plus `playwright install chromium` once) and a [Cap.Guru](https://cap.guru) API key.

## Links

- Package on PyPI: [capguru-mcp](https://pypi.org/project/capguru-mcp/)
- Official MCP Registry: `guru.cap/capguru-mcp`
- Captcha demo pages to test the server: [test.cap.guru/demo](https://test.cap.guru/demo/)
- Support: [Telegram @captcha_guru](https://t.me/captcha_guru), support@cap.guru

## License

MIT, see [LICENSE](LICENSE). Use the server in line with the law and the terms of the websites you work with.

---

## Кратко на русском

**capguru-mcp** подключает сервис решения капчи Cap.Guru к ИИ-ассистентам: Claude, Cursor, Windsurf, VS Code, Gemini CLI и другим клиентам MCP. Ассистент сам открывает страницу, находит капчу, решает её и продолжает работу.

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

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

Настройка клиентов, список инструментов и примеры: [документация на русском](https://docs.cap.guru/ru/modules/mcp.html).