Metadata-Version: 2.4
Name: captchaflow-mcp
Version: 0.1.0
Summary: MCP server exposing the CaptchaFlow captcha-solving API as tools
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.2
Requires-Dist: httpx>=0.27

# captchaflow-mcp

MCP (Model Context Protocol) stdio server exposing the [CaptchaFlow](https://captcha.dataleads.pro) captcha-solving API as AI-usable tools.

Lets MCP clients (Claude Desktop, etc.) solve reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, and image captchas on demand.

## Install

```bash
cd captchaflow-mcp
pip install -e .
```

Installs the `captchaflow-mcp` command and the `captchaflow_mcp` package (requires Python 3.10+ and the `mcp` package).

## Configuration

Environment variables (read when the server starts):

| Variable | Required | Default |
|---|---|---|
| `CAPTCHAFLOW_KEY` | yes | — (server exits with a clear error if missing) |
| `CAPTCHAFLOW_BASE_URL` | no | `https://captcha.dataleads.pro/v1` |

## Tools

| Tool | Returns |
|---|---|
| `solve_image(image_path)` | Recognized text from an image captcha (ImageToTextTask) |
| `solve_recaptcha(website_url, site_key, v3=False, score=0.9)` | reCAPTCHA `gRecaptchaResponse` token (v2, or v3 with min score) |
| `solve_hcaptcha(website_url, site_key)` | hCaptcha response token |
| `solve_turnstile(website_url, site_key)` | Turnstile token |
| `get_balance()` | Account balance (float) |
| `health()` | API health dict (no auth) |

Solve tools submit a task via `POST /createTask` and poll `POST /getTaskResult` every 3 s (120 s max), mirroring the CLI.

## Claude Desktop config

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "captchaflow": {
      "command": "python",
      "args": ["-m", "captchaflow_mcp.server"],
      "env": {
        "CAPTCHAFLOW_KEY": "your_client_key"
      }
    }
  }
}
```

If `python` is not on the PATH of the MCP host, use the absolute interpreter path, e.g. `/opt/venv/bin/python`.

## Run manually

```bash
captchaflow-mcp
# or
python -m captchaflow_mcp.server
```

The server speaks MCP over stdio; it is meant to be launched by an MCP client, not interactively.

## Library use

```python
from captchaflow_mcp import CaptchaFlowClient

client = CaptchaFlowClient(client_key="your_client_key")
solution = client.solve({"type": "TurnstileTaskProxyless", "websiteURL": "https://example.com", "websiteKey": "key"})
print(solution.get("token"))
```
