# CAPTCHA Solver MCP Server: ZeroCaptcha in Claude Code and Cursor

> Set up the ZeroCaptcha MCP server in Claude Code and Cursor: its four tools, the settings, keeping the key out of your repository, and when to use it.

- Source: https://zerocaptcha.io/blog/captcha-solver-mcp-server
- Published: 2026-10-01
- Author: ZeroCaptcha Engineering

The **ZeroCaptcha MCP server** lets an AI assistant that speaks the Model Context Protocol, such as
**Claude Code**, Claude Desktop or **Cursor**, call ZeroCaptcha itself. It has four tools:
`create_task` (solve a Cloudflare Turnstile widget, or a Cloudflare challenge page through your
proxy, and wait for the result), `get_task_result`, `get_balance` and `search_docs`. It runs locally
over stdio on Node.js 20 or later and reads three settings from its environment: `ZEROCAPTCHA_KEY`,
`ZEROCAPTCHA_API` and `ZEROCAPTCHA_DOCS`. Every task it creates is real and charged when it succeeds,
so give it a key with a daily spend cap.

This tutorial covers what the tools do, the setup in both clients, how to keep the key out of your
repository, and when an MCP server is the right tool. The server is not in a package registry yet
(coming). Until it is, give your assistant the [integration brief](https://zerocaptcha.io/ai/integration.md), which covers
every call the server makes, or call the API over plain HTTP as the [quickstart](https://zerocaptcha.io/docs/quickstart)
does.

## The four tools

| Tool | Arguments | What it does |
| --- | --- | --- |
| `create_task` | `websiteURL`, and `websiteKey` for Cloudflare Turnstile; optionally `type`, `action`, `cdata`, `proxy`, `wait` (default `true`), `timeoutSeconds` (default 180) | Creates a Cloudflare Turnstile task (`TurnstileTask` with a proxy, `TurnstileTaskProxyless` without) and waits for its token; with `type` `CloudflareChallengeTask` and a `proxy`, passes a challenge page and gives its `cfClearance` and `userAgent` |
| `get_task_result` | `taskId` | The task's status, cost, error code, and token while it is valid |
| `get_balance` | none | The available and held balance, in US dollars |
| `search_docs` | `query`, and optionally `limit` (1 to 10, default 3) | The docs sections that best match, from `/llms-full.txt`, with their links |

A task that fails, a wait that runs out, and a refusal from the API come back as tool errors, with
the code, such as `ERROR_CAPTCHA_UNSOLVABLE` or `insufficient_funds`. The server calls the API
through the official SDK, which retries what a retry can fix and sends an `Idempotency-Key` with
every create, so a retry never makes a second task.

## Settings

| Variable | What it is |
| --- | --- |
| `ZEROCAPTCHA_KEY` | Your API key, `zc_live_…`, from the dashboard's API keys page. Needed by the API tools. |
| `ZEROCAPTCHA_API` | The API's address: `https://api.zerocaptcha.io` when unset. Used by the API tools. |
| `ZEROCAPTCHA_DOCS` | The docs site's address: `https://zerocaptcha.io` when unset. Used by `search_docs`. |

The server never writes the key to a reply or a log.

## Claude Code

Claude Code adds a local stdio server with `claude mcp add [options] <name> -- <command> [args...]`,
and its docs say "The `--` (double dash) separator is required": everything after it is the command
that starts the server.

```sh
claude mcp add zerocaptcha --env ZEROCAPTCHA_KEY=$ZEROCAPTCHA_KEY \
  --env ZEROCAPTCHA_API=$ZEROCAPTCHA_API --env ZEROCAPTCHA_DOCS=$ZEROCAPTCHA_DOCS \
  -- node /path/to/zerocaptcha-mcp/dist/main.js

claude mcp list
```

`claude mcp list` shows the configured servers, and `/mcp` inside a session shows their status. By
default the server is added in the **local** scope, stored in `~/.claude.json` and not shared. To
share it with your team through version control, use `--scope project`, which writes `.mcp.json` in
the project root. Never commit a key there: Claude Code expands `${VAR}` in a project's `.mcp.json`,
so the file can name the variable and each person's environment supplies the value.

```json
{
  "mcpServers": {
    "zerocaptcha": {
      "command": "node",
      "args": ["/path/to/zerocaptcha-mcp/dist/main.js"],
      "env": {
        "ZEROCAPTCHA_KEY": "${ZEROCAPTCHA_KEY}",
        "ZEROCAPTCHA_API": "${ZEROCAPTCHA_API}",
        "ZEROCAPTCHA_DOCS": "${ZEROCAPTCHA_DOCS}"
      }
    }
  }
}
```

## Cursor

Cursor reads MCP servers from `.cursor/mcp.json` in a project or `~/.cursor/mcp.json` in your home
directory, with the same `command`, `args` and `env` shape. For stdio servers it interpolates
`${env:NAME}` from your environment, and it can load an `envFile`:

```json
{
  "mcpServers": {
    "zerocaptcha": {
      "command": "node",
      "args": ["/path/to/zerocaptcha-mcp/dist/main.js"],
      "env": {
        "ZEROCAPTCHA_KEY": "${env:ZEROCAPTCHA_KEY}",
        "ZEROCAPTCHA_API": "${env:ZEROCAPTCHA_API}",
        "ZEROCAPTCHA_DOCS": "${env:ZEROCAPTCHA_DOCS}"
      }
    }
  }
}
```

Cursor's docs say it "asks for approval before using MCP tools by default". Keep it that way for
`create_task`: each approval is a paid task.

## What to ask it

Once the server is connected, ask in plain words. For example:

- "What's my ZeroCaptcha balance?" (`get_balance`)
- "Search the ZeroCaptcha docs for what to do after rate_limited." (`search_docs`)
- "Solve the Cloudflare Turnstile widget on https://staging.example.com/login, sitekey
  0x4AAAAAAAB1cD2eF3gH4iJ5, and show me the token's expiry." (`create_task`)

The token works once, for 300 seconds, so it is useful for checking an integration by hand, not for
storing. The assistant sees the token in the tool result: use tokens only for pages you are allowed
to automate, and never paste your key into the chat.

## When to use the MCP server, and when not

- **Good fits:** checking that a page's sitekey and action are right before you write code; asking
  the docs a question from inside your editor; looking at a task that failed, by ID; checking the
  balance.
- **Not a fit:** production pipelines. A crawler or a scheduled job should call the API directly,
  with the [SDKs](https://zerocaptcha.io/docs/sdks) or plain HTTP, so it does not depend on an assistant's session. To
  have an assistant write that code for you, give it the integration brief instead: see
  [hand off a CAPTCHA API integration to an AI coding assistant](https://zerocaptcha.io/blog/ai-coding-assistant-captcha-integration).

Two cautions from the clients' own docs apply. Claude Code says: "Verify you trust each server
before connecting it", since "Servers that fetch external content can expose you to prompt
injection risk". And cost: cap each key's daily spend in the dashboard, and give the MCP server a key of its own.
See [secure captcha API keys](https://zerocaptcha.io/guides/secure-captcha-api-keys). How automated solving works, in
plain terms, is in [AI CAPTCHA solvers and Cloudflare Turnstile](https://zerocaptcha.io/blog/ai-captcha-solver).

## Sources

- [ZeroCaptcha docs: hand off to AI](https://zerocaptcha.io/docs/ai), the MCP server section (checked 1 October 2026).
- [Claude Code: MCP](https://code.claude.com/docs/en/mcp) (checked 1 October 2026).
- [Cursor: Model Context Protocol](https://cursor.com/docs/mcp) (checked 1 October 2026).
- [Model Context Protocol](https://modelcontextprotocol.io) (checked 1 October 2026).

## Questions

### What does the ZeroCaptcha MCP server do?

It is not in a package registry yet (coming). It lets an assistant that speaks the Model Context Protocol, such as Claude Code, Claude Desktop or Cursor, create a Cloudflare Turnstile or Cloudflare challenge page task and wait for its result, read a task, read the balance, and search the ZeroCaptcha docs, over stdio.

### How do I add the ZeroCaptcha MCP server to Claude Code?

Run claude mcp add with a name, the three settings as --env options, then -- and the command that starts the server: node and the path to its dist/main.js. Claude Code's docs say the -- separator is required.

### Are tasks made through the MCP server free?

No. Every task it creates is real and charged from your prepaid balance if it succeeds; a failed task costs nothing. Give the server a key with a daily spend cap.