guru.cap/capguru-mcp

capguru-mcp is a Model Context Protocol server that connects the 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.

Related MCP server: puppeteer-real-browser-mcp-server

Supported captchas

Quick start

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:

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

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.

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

Settings

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 API key.

Links

• Package on PyPI: capguru-mcp

• Official MCP Registry: guru.cap/capguru-mcp

• Captcha demo pages to test the server: test.cap.guru/demo

• Support: Telegram @captcha_guru, support@cap.guru

License

MIT, see 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 и текстовые капчи.

pip install capguru-mcp
playwright install chromium

Настройка клиентов, список инструментов и примеры: документация на русском.