CAPTCHA Solver MCP Server: ZeroCaptcha in Claude Code and Cursor

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, which covers every call the server makes, or call the API over plain HTTP as the quickstart does.

The four tools

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

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.

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.

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

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

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. How automated solving works, in plain terms, is in AI CAPTCHA solvers and Cloudflare Turnstile.

Sources

• ZeroCaptcha docs: hand off to AI, the MCP server section (checked 1 October 2026).
• Claude Code: MCP (checked 1 October 2026).
• Cursor: Model Context Protocol (checked 1 October 2026).
• Model Context Protocol (checked 1 October 2026).

The team that builds and runs the ZeroCaptcha API. Articles are drafted with AI tools, then checked against the API's code and the primary sources each one cites.