Easy Captcha

📘 这是英文版 README。中文版本请见：README_CN.md

Easy Captcha is an OCR-based captcha recognition service built on RapidOCR. It supports recognizing pure digits, alphanumeric mixes, and solving simple arithmetic expressions. The project provides both FastAPI and MCP interfaces.

Supported Captcha Types

Type	Example	Result
Pure digits	1234	1234
Alphanumeric mix	A1B2 / abc123	A1B2 / abc123
Addition	3+5=?	8
Subtraction	12-7=?	5
Multiplication	4×2=? / 4*2 / 4x2	8
Division	15÷3=? / 8/2	5 / 4

Installation

uv sync

Usage

FastAPI

uv run main.py  # simple run
uv run uvicorn main:app  # better performance

The service listens on 0.0.0.0:8000 by default. API docs are available at http://localhost:8000/docs.

Upload an image file:

curl -X POST http://localhost:8000/ocr/file \
  -F "file=@captcha.png"

Submit a Base64-encoded image:

curl -X POST http://localhost:8000/ocr/base64 \
  -H "Content-Type: application/json" \
  -d '{"image": "<base64-encoded-image>"}'

Response format:

{
  "raw_text": "3+5=?",
  "result": "8"
}

MCP

uv run mcp_server.py

This uses stdio by default and works with MCP clients like Claude Desktop.

Client configuration example:

{
  "mcpServers": {
    "easy-captcha": {
      "command": "uv",
      "args": ["run", "mcp_server.py"],
      "cwd": "/path/to/easy_captcha"
    }
  }
}

Available tool:

• solve_captcha(image_base64: str) — send a Base64-encoded captcha image; returns OCR text (supports digits/letters mix) and the computed result.

Project Structure

easy_captcha/
├── pyproject.toml      # project configuration and dependencies
├── captcha_solver.py   # core OCR + expression parsing
├── main.py             # FastAPI service
└── mcp_server.py       # MCP service

Acknowledgements

Thanks to:

• PaddleOCR
• RapidOCR
• Claude Code
• VSCode

License

The copyright of the OCR model is held by Baidu, while the copyrights of all other engineering scripts are retained by the repository owner.

This project is released under the Apache License 2.0.

By:

Les1ie

2026.3.8