API Documentation

npx uncaptcha-mcp setup

claude mcp add uncaptcha -e UNCAPTCHA_API_KEY=ac-your-key -- npx uncaptcha-mcp

{
  "mcpServers": {
    "uncaptcha": {
      "command": "npx",
      "args": ["uncaptcha-mcp"],
      "env": {
        "UNCAPTCHA_API_KEY": "ac-your-api-key-here"
      }
    }
  }
}

from uncaptcha import Uncaptcha

solver = Uncaptcha("ac-your-api-key")

# Solve reCAPTCHA v2
result = solver.recaptcha(
    site_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    page_url="https://www.google.com/recaptcha/api2/demo",
)
print(f"Token: {result['token'][:50]}...")

# Use the token in a form submission
import requests

response = requests.post("https://example.com/submit", data={
    "g-recaptcha-response": result["token"],
    "username": "user",
    "password": "pass",
})
print(f"Status: {response.status_code}")

import requests

response = requests.post(
    "https://api.uncaptcha.dev/v1/solve/sync",
    headers={
        "X-API-Key": "ac-your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "type": "turnstile",
        "siteKey": "0x4AAAAAAABS7vwvV6VFfMcD",
        "pageUrl": "https://example.com",
    },
    timeout=130,
)

data = response.json()
if data.get("status") == "solved":
    print(f"Solved in {data['elapsed']}ms")
    print(f"Token: {data['token'][:50]}...")
else:
    print(f"Failed: {data}")

from pathlib import Path
from uncaptcha import Uncaptcha

solver = Uncaptcha("ac-your-api-key")

# From file path
result = solver.image(Path("captcha.png"))
print(f"Text: {result['token']}")

# From base64 string
import base64

with open("captcha.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

result = solver.image(b64)
print(f"Text: {result['token']}")

import { Uncaptcha } from 'uncaptcha';

const solver = new Uncaptcha('ac-your-api-key');

// Solve reCAPTCHA v2
const { token } = await solver.recaptcha({
  siteKey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
  pageUrl: 'https://www.google.com/recaptcha/api2/demo',
});

console.log('Token:', token.substring(0, 50) + '...');

// Use the token in a form submission
const response = await fetch('https://example.com/submit', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    'g-recaptcha-response': token,
    username: 'user',
    password: 'pass',
  }),
});
console.log('Status:', response.status);

const response = await fetch('https://api.uncaptcha.dev/v1/solve/sync', {
  method: 'POST',
  headers: {
    'X-API-Key': 'ac-your-api-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'turnstile',
    siteKey: '0x4AAAAAAABS7vwvV6VFfMcD',
    pageUrl: 'https://example.com',
  }),
  signal: AbortSignal.timeout(130_000),
});

const data = await response.json();

if (data.status === 'solved') {
  console.log(`Solved in ${data.elapsed}ms`);
  console.log('Token:', data.token.substring(0, 50) + '...');
} else {
  console.error('Failed:', data);
}

import { Uncaptcha, AuthenticationError, QuotaExceededError, NetworkError } from 'uncaptcha';

const solver = new Uncaptcha('ac-your-api-key');

try {
  const { token } = await solver.recaptcha({
    siteKey: '6Le-abc...',
    pageUrl: 'https://example.com',
  });
  console.log('Solved:', token);
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Invalid API key. Check your dashboard.');
  } else if (err instanceof QuotaExceededError) {
    console.error('Monthly quota exceeded. Upgrade your plan.');
  } else if (err instanceof NetworkError) {
    console.error('Network issue. Retrying...');
  } else {
    console.error('Unexpected error:', err.message);
  }
}

curl -X POST https://api.uncaptcha.dev/v1/solve/sync \
  -H "X-API-Key: ac-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "recaptcha_v2",
    "siteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    "pageUrl": "https://www.google.com/recaptcha/api2/demo"
  }'

# Step 1: Submit the solve request
RESPONSE=$(curl -s -X POST https://api.uncaptcha.dev/v1/solve \
  -H "X-API-Key: ac-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "turnstile",
    "siteKey": "0x4AAAAAAABS7vwvV6VFfMcD",
    "pageUrl": "https://example.com"
  }')

echo "$RESPONSE"

# Step 2: Extract the taskId and retrieve the result
TASK_ID=$(echo "$RESPONSE" | jq -r '.taskId')

curl -s https://api.uncaptcha.dev/v1/result/$TASK_ID \
  -H "X-API-Key: ac-your-api-key" | jq .

curl -s https://api.uncaptcha.dev/v1/balance \
  -H "X-API-Key: ac-your-api-key" | jq .

curl -X POST https://api.uncaptcha.dev/v1/report \
  -H "X-API-Key: ac-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "correct": true
  }'

# Latest 20 solves
curl -s "https://api.uncaptcha.dev/v1/history?limit=20" \
  -H "X-API-Key: ac-your-api-key" | jq .

# Filter by type
curl -s "https://api.uncaptcha.dev/v1/history?type=turnstile&limit=10" \
  -H "X-API-Key: ac-your-api-key" | jq .