solvehub-mcp

MCP server for the SolveHub CAPTCHA and anti-bot solver API. Gives Claude, Cursor, VS Code and any other MCP client eight tools to solve a challenge and get the token, cookie or OCR text back - Turnstile, Interstitial, DataDome, Akamai, PerimeterX, Imperva, AWS WAF, Alibaba CAPTCHA 2.0, Arkose FunCaptcha and image OCR through a single REST endpoint.

Zero dependencies, one npx command, Node 18 or newer.

Tools

Related MCP server: 2Captcha MCP

Install

Get an API key from the SolveHub console; new accounts get a $0.10 trial credit after Telegram verification.

Claude Desktop

Edit claude_desktop_config.json and restart the app:

{
  "mcpServers": {
    "solvehub": {
      "command": "npx",
      "args": ["-y", "github:seencxy/solvehub-mcp"],
      "env": { "SOLVEHUB_API_KEY": "sh_live_xxx" }
    }
  }
}

Cursor, VS Code, Cline, Windsurf

Most clients read the same JSON in mcp.json (VS Code and Cursor use the servers key):

{
  "servers": {
    "solvehub": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:seencxy/solvehub-mcp"],
      "env": { "SOLVEHUB_API_KEY": "sh_live_xxx" }
    }
  }
}

From a clone

git clone https://github.com/seencxy/solvehub-mcp
cd solvehub-mcp
SOLVEHUB_API_KEY=sh_live_xxx node index.mjs

Docker

A public image is built from this repo on every push to main, so no local Node install is needed:

docker run -i --rm -e SOLVEHUB_API_KEY=sh_live_xxx ghcr.io/seencxy/solvehub-mcp:latest

Claude Desktop (or any stdio client) can launch the same image:

{
  "mcpServers": {
    "solvehub": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "SOLVEHUB_API_KEY=sh_live_xxx", "ghcr.io/seencxy/solvehub-mcp:latest"]
    }
  }
}

What it looks like in use

Solve the Cloudflare Turnstile on https://example.com/login. The site key is 0x4AAAAAAA... and I am allowed to test this site.

The model calls solve_captcha with type: turnstile and the challenge fields, then answers with the token and its expiry. Anything that needs a proxy (DataDome, Imperva, Akamai, PerimeterX) takes a proxy argument as well, for example http://user:pass@host:port.

Environment variables

Billing behaviour you should know

• The price is frozen when the task is created, charged only when it completes, and refunded if the task fails or is cancelled. A failed challenge costs nothing.

• The server sends an Idempotency-Key on every create, and retries 429/5xx and network errors with exponential backoff, so a retry cannot bill the same task twice.

• get_balance and get_prices are there so an agent can check the cost before spending anything.

• uncertain is not a failure: the challenge could not be judged yet and can still resolve, so wait_for_task keeps polling instead of giving up.

Supported challenge types

Exact field names per type are in the API reference.

Development

npm test

The tests run the JSON-RPC dispatcher, the tool schemas and the polling state machine against a mocked HTTP layer, so they need no API key and no network.

Related

• solvehub-python - Python SDK, also dependency free

• solvehub-node - Node SDK

• API documentation

Legal

Use it on systems you own or have written permission to test. That is what the API is for, and the terms say the same thing.

MIT licensed.