MCP Server for Solving Captchas

logo

MCP server (capguru-mcp) connects the captcha solving service to AI assistants and agents: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code with GitHub Copilot, Cline, Zed, Gemini CLI, OpenAI Codex CLI and any other client that supports the Model Context Protocol.
The assistant opens the page in a browser, finds the captcha, solves it and continues the task. Just describe what you need in plain language.

Latest Version

Version	Changes	Download
0.2	Release	PyPI

What Is an MCP Server

The Model Context Protocol (MCP) is an open standard that lets AI assistants use external tools.
The MCP server gives the assistant tools for browser control and captcha solving. The assistant calls them by itself when the task requires it.

What the server can do:

Solve captchas on a page in the browser: reCAPTCHA v2, hCaptcha, GeeTest v3/v4, FunCaptcha (Arkose Labs), TikTok, AWS WAF, Other.
Detect the captcha type on the page automatically.
Get reCAPTCHA v2, v2 Invisible, v3 and Cloudflare Turnstile tokens, including without a browser, by sitekey and page URL.
Recognize text captchas from images and type the answer into an input.
Open pages, click buttons, fill in forms and take screenshots.
Connect to an already running Chrome controlled by another tool.

Installation

The server is published on PyPI. Python 3.10 or newer is required.

pip install capguru-mcp
playwright install chromium

Update to the latest version:

pip install -U capguru-mcp

Your API key is passed through the CAPGURU_API_KEY environment variable in the client settings. The key stays in your local config and is sent only to our API server.

Connecting to MCP Clients

Most clients use the same format with the mcpServers key. Only the file location and, for a few clients, the key name differ.

Claude Desktop

File 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": "YOUR_KEY" }
    }
  }
}

Restart Claude Desktop after editing the config.

Claude Code

bash

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

Cursor

File ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in the project folder. Same format as Claude Desktop:

json

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

Windsurf

File ~/.codeium/windsurf/mcp_config.json (Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json). Same format with the mcpServers key. Restart Windsurf after editing.

VS Code (GitHub Copilot)

File .vscode/mcp.json in the project folder. Note that VS Code uses the servers key instead of mcpServers.

json

{
  "servers": {
    "capguru": {
      "type": "stdio",
      "command": "capguru-mcp",
      "env": { "CAPGURU_API_KEY": "YOUR_KEY" }
    }
  }
}

MCP tools are available in Copilot Chat Agent mode.

Visual Studio

File %USERPROFILE%\.mcp.json or .mcp.json in the solution folder. Same format as VS Code. The tools are available in GitHub Copilot Chat Agent mode.

Cline and Roo Code

Open the MCP Servers section in the extension and click "Configure MCP Servers". Add the capguru block in the mcpServers format, the same as for Claude Desktop.

Continue

File ~/.continue/config.yaml:

yaml

mcpServers:
  - name: capguru
    command: capguru-mcp
    env:
      CAPGURU_API_KEY: YOUR_KEY

Zed

Zed settings.json (Linux: ~/.config/zed/settings.json, Windows: %APPDATA%\Zed\settings.json). Zed uses the context_servers key:

json

{
  "context_servers": {
    "capguru": {
      "command": "capguru-mcp",
      "args": [],
      "env": { "CAPGURU_API_KEY": "YOUR_KEY" }
    }
  }
}

Gemini CLI

File ~/.gemini/settings.json (all projects) or .gemini/settings.json in the project folder. Same mcpServers format as Claude Desktop.

OpenAI Codex CLI

File ~/.codex/config.toml. Codex uses TOML:

toml

[mcp_servers.capguru]
command = "capguru-mcp"
env = { CAPGURU_API_KEY = "YOUR_KEY" }

Other Clients

Amazon Q Developer CLI (~/.aws/amazonq/mcp.json), GitHub Copilot CLI (~/.copilot/mcp-config.json), Google Antigravity and other MCP clients use the same mcpServers format. Set the command to capguru-mcp and the CAPGURU_API_KEY variable.

If the client cannot find the capguru-mcp command

On Windows the Python Scripts folder may be missing from PATH, and desktop apps do not always see the terminal PATH. Run the server through Python: "command": "python", "args": ["-m", "capguru_mcp"] or use the full path to capguru-mcp.

Running without installation via uv

If uv is installed, the server can run without pip install: "command": "uvx", "args": ["capguru-mcp"]

Usage

Once connected, just describe the task to the assistant. It decides which tools to call.

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

Solving Captchas in the Browser

The solve_captcha tool solves the captcha right on the open page: it clicks images, drags sliders and completes multi-step challenges.
In auto mode the server detects the captcha type and waits for it to appear. Supported: reCAPTCHA v2, hCaptcha, GeeTest v3 and v4, FunCaptcha (Arkose Labs), TikTok, AWS WAF and Other.

reCAPTCHA and Cloudflare Turnstile Tokens

The solve_recaptcha_token and solve_turnstile_token tools get a ready token from the service without solving images in the browser.
Without a browser, the sitekey and page URL are enough: the token is returned as text and can be used in your own requests.
If a page is open, the sitekey and URL are taken from it, and a reCAPTCHA v2 or Turnstile token is inserted into the page and the site callback is called.
A reCAPTCHA v3 token is only returned, because v3 sites request it themselves.

Text Captcha Recognition

The solve_image_captcha tool recognizes a captcha from an image: a page element, a file, a URL or base64.
Use vernet to set the captcha kind (Yandex, VKontakte, arithmetic and others) and fill_selector to type the answer into an input.

Tools

Browser:

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
`close_browser`	Close the browser

Captcha:

Tool	Description
`detect_captcha`	Detect the captcha type on the page without solving
`solve_captcha`	Solve the captcha on the page: `auto` or a specific type
`solve_recaptcha_token`	Get a reCAPTCHA v2 / v2 Invisible / v3 token (`sitekey`, `pageurl`, `version`, `min_score`)
`solve_turnstile_token`	Get a Cloudflare Turnstile token (`sitekey`, `pageurl`)
`solve_image_captcha`	Recognize a text captcha from an image (`selector`, `image_base64`, `image_path` or `image_url`; `vernet`, `fill_selector`)

Supported Captchas

reCaptcha2	reCaptcha3	Turnstile	FunCaptcha	TikTok	GeeTest	AWS WAF	hCaptcha	Text	Other
Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes

Parameters

Set as environment variables in the env block of the client config.

Variable	Default	Description
`CAPGURU_API_KEY`	-	API key (required)
`CAPGURU_SERVER`	`https://api.cap.guru`	API server
`CAPGURU_ATTEMPTS`	`5`	Max number of attempts
`CAPGURU_DEBUG`	`1`	Include the solver log in replies to the assistant
`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

Error Handling

Errors are returned to the assistant as plain text, and it reports them in its reply:

Message	Cause
`Cap.Guru account error (API key or balance)`	Invalid API key or zero balance
`Not solved: ERROR_CAPTCHA_UNSOLVABLE`	The captcha could not be solved after all attempts
`No captcha found within 30 s`	No captcha appeared on the page
`No browser page. Call open_browser or connect_browser first.`	The browser is not open yet
`CAPGURU_API_KEY environment variable is not set`	The API key is missing from the client config

FAQ

Which AI assistants are supported?

Any client that supports the Model Context Protocol: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code and Visual Studio with GitHub Copilot, Cline, Roo Code, Continue, Zed, Gemini CLI, OpenAI Codex CLI, Amazon Q Developer CLI and others.

Do I need a browser to solve captchas?

To solve a captcha on a page, yes: the server launches Chromium or an installed Chrome / Edge.
reCAPTCHA and Cloudflare Turnstile tokens can be obtained without a browser: the sitekey and page URL are enough.

Can it solve captchas in a browser controlled by another MCP server?

Yes. Start Chrome with --remote-debugging-port=9222 and ask the assistant to connect with connect_browser. The server will work with the same tab.

Does the server work through a proxy?

Yes. Pass the proxy to open_browser in the http://user:password@host:port format.

Where is the API key stored?

Only in your MCP client config on your computer. The server sends the key only to our API.

How is the MCP server different from the Python and Node.js modules?

The modules are used in the code of your scripts. The MCP server requires no programming: an AI assistant controls it with plain-language requests.

MCP Server for Solving Captchas ​

Latest Version ​

What Is an MCP Server ​

Installation ​

Connecting to MCP Clients ​

Claude Desktop ​

Claude Code ​

Cursor ​

Windsurf ​

VS Code (GitHub Copilot) ​

Visual Studio ​

Cline and Roo Code ​

Continue ​

Zed ​

Gemini CLI ​

OpenAI Codex CLI ​

Other Clients ​

Usage ​

Solving Captchas in the Browser ​

reCAPTCHA and Cloudflare Turnstile Tokens ​

Text Captcha Recognition ​

Tools ​

Supported Captchas ​

Parameters ​

Error Handling ​

FAQ ​

Which AI assistants are supported? ​

Do I need a browser to solve captchas? ​

Can it solve captchas in a browser controlled by another MCP server? ​

Does the server work through a proxy? ​

Where is the API key stored? ​

How is the MCP server different from the Python and Node.js modules? ​

MCP Server for Solving Captchas

Latest Version

What Is an MCP Server

Installation

Connecting to MCP Clients

Claude Desktop

Claude Code

Cursor

Windsurf

VS Code (GitHub Copilot)

Visual Studio

Cline and Roo Code

Continue

Zed

Gemini CLI

OpenAI Codex CLI

Other Clients

Usage

Solving Captchas in the Browser

reCAPTCHA and Cloudflare Turnstile Tokens

Text Captcha Recognition

Tools

Supported Captchas

Parameters

Error Handling

FAQ

Which AI assistants are supported?

Do I need a browser to solve captchas?

Can it solve captchas in a browser controlled by another MCP server?

Does the server work through a proxy?

Where is the API key stored?

How is the MCP server different from the Python and Node.js modules?