captcha-mcp-test

MCP server for solving captchas via CapMonster Cloud. It is the solve brain: it lists supported captcha types, serves CapMonster's docs, and creates/polls solve tasks against the CapMonster Cloud REST API. It has no browser of its own — pair it with a browser-driving MCP (e.g. mcp-patchright-mainworld) that does the page work (navigation, interaction, reading the live DOM/network, and injecting the solved token back into the page).

Two equivalent implementations live in this repo, same tools/behavior:

• Python (this directory) — published to PyPI, run with uvx.
• TypeScript (ts/) — published to npm, run with npx. See ts/README.md.

Quick start (Python / PyPI)

{
  "mcpServers": {
    "capmonster": {
      "command": "uvx",
      "args": ["captcha-mcp-test"],
      "env": { "CM_API_KEY": "YOUR_API_KEY" }
    }
  }
}

uvx runs the published PyPI package with no local clone needed. See mcp.json for a full example that also wires up the patchright companion browser MCP.

For the npm/TypeScript version, see ts/README.md.

Configuration

This server only runs over stdio (the transport MCP clients use to launch it as a subprocess), so there are no HTTP headers to carry a per-request key — set CM_API_KEY in the client's env block (see mcp.json) and every tool call in that session uses it.

Tools

• get_supported_tasks — list captcha task types CapMonster supports (from the live OpenAPI spec).
• get_task_parameters(task_type) — required/optional fields, variant notes, and the solution schema for a task type.
• get_docs(url, offset, limit, section) — fetch a CapMonster doc page (docs.capmonster.cloud/api.capmonster.cloud only), with section-jump and pagination.
• create_task(task) — submit a captcha task, returns a taskId.
• get_task_result(task_id) — poll a task once.
• get_task_result_wait(task_id, timeout_seconds, poll_interval_seconds) — poll a task to completion (preferred over driving the loop yourself).
• get_actual_user_agent() — fetch a current Windows User-Agent to use as one consistent fingerprint across the browser and the solve task.
• get_balance() — CapMonster account balance.

Workflow

capmonster_agent/SKILL.md is the step-by-step procedure for analyzing a captcha-protected page and solving it with this server paired with a patchright (or any stateful browser-automation) MCP. capmonster_agent/PROMPT.md is a copy-paste prompt that sets an agent up with both servers (Python/PyPI capmonster server via uvx) and points it at the skill. capmonster_agent/PROMPT_JS.md is the same prompt for the TypeScript/npm capmonster server, run via npx.

Development

python -m venv .venv
.venv\Scripts\activate  # or source .venv/bin/activate on Linux/macOS
pip install -e ".[dev]"
pytest