convez.ai
MCP ServerIntegração & APIsIntermediário
21010

MCP OCR API

21010/mcp-ocr-api

OCR offline otimizado para edge com suporte a PDF e TIFF

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP de OCR rápido e totalmente offline, otimizado para dispositivos edge sem GPU. Processa imagens, PDFs multipage e TIFFs usando RapidOCR e ONNX Runtime, expondo interfaces REST e MCP.

Instalação

$npx convez-ai 21010/mcp-ocr-api

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Extrair texto de documentos em ambientes sem conexão à internet
  • Processar PDFs multipage em dispositivos com recursos limitados
  • Integrar OCR em pipelines de automação com Claude via MCP
  • Deployar OCR serverless em Azure Functions

Veredito

MCP OCR robusto para casos reais de processamento de documentos offline. Excelente para automação documental edge, mas requer Python 3.10+ e setup inicial.

README

A tradução para o português deste README ainda está na fila.

MCP OCR Service

Python Version uv FastAPI MCP Linting: Ruff Security: Bandit Azure Functions CI/CD

A simple, robust, and highly optimized API and Model Context Protocol (MCP) server for Optical Character Recognition (OCR) on documents.

Table of Contents


Overview

This project provides fast, fully offline OCR capabilities tailored for edge devices and non-GPU environments. It leverages RapidOCR and ONNXRuntime under the hood to ensure rapid processing without relying on heavy deep-learning frameworks like PyTorch or expensive cloud APIs.

It is designed following SOLID and CUPID principles, keeping the architecture stateless and easily integrable with Large Language Models (LLMs) via FastMCP.

Features

  • Broad Format Support: Seamlessly processes standard images (PNG, JPG), multipage PDFs (via pypdfium2), and multipage TIFFs (via Pillow).
  • Fully Offline & CPU-Optimized: Runs beautifully on edge devices with configurable thread counts and memory limits.
  • Dual Interfaces: Exposes both a standard REST API (FastAPI) and an MCP Server (FastMCP via SSE and stdio).
  • Cloud Ready: Natively wrapped for serverless deployment on Azure Functions.
  • Secure & Configurable: Features configurable CORS, host bindings, and strict file size limits to prevent edge OOMs.

Installation & Setup

Prerequisites

  • Python 3.10+
  • uv (Extremely fast Python package manager)

Local Setup

Clone the repository and sync the environment:

git clone https://github.com/21010/mcp-ocr-api.git
cd mcp-ocr-api
uv sync

Configuration

Configure the server using environment variables (managed via pydantic-settings). Defaults are highly optimized for edge limits:

VariableDefaultDescription
OCR_HOST0.0.0.0The network interface the API binds to.
OCR_PORT8000The port for the FastAPI server.
OCR_CORS_ORIGINS["*"]Allowed CORS origins for the web API.
OCR_API_KEYNoneOptional API Key to secure the REST endpoint.
OCR_MAX_FILE_SIZE10485760 (10MB)Maximum allowed upload file size.
OCR_INTRA_OP_THREADS2ONNX runtime intra-op threads.
OCR_INTER_OP_THREADS1ONNX runtime inter-op threads.
OCR_MAX_CONCURRENT1Max concurrent OCR jobs allowed.

Deployment & Running

1. Run the REST API & MCP SSE Endpoint

uv run mcp-ocr-api

The API starts on http://localhost:8000. Swagger docs at /docs.

2. Run the MCP Server (stdio mode)

uv run mcp-ocr-stdio

Starts the FastMCP server, allowing LLMs to connect directly via standard input/output.

3. Docker Deployment

A fully optimized Dockerfile and docker-compose.yml are provided.

docker compose up --build -d

4. Azure Functions Deployment

This project is configured to run on Azure Functions via the Python v2 programming model. Run locally:

func start

Deploy directly to Azure:

func azure functionapp publish <YourFunctionAppName>

Usage & Integrations

Via REST API

Health Check

curl http://localhost:8000/health

OCR File Upload

curl -X POST http://localhost:8000/api/v1/ocr \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/absolute/path/to/document.pdf"

LLM Client Setup (Claude Desktop)

To use this OCR server as a tool in Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-ocr": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-ocr-api",
        "mcp-ocr-stdio"
      ]
    }
  }
}

Once connected, you can prompt the LLM naturally:

  • "Read the text from the document located at C:/Users/user/Desktop/scanned.pdf"
  • "I have this base64 string of an image. Can you tell me what it says? iVBORw0..."

Project Structure

mcp-ocr-api/
├── pyproject.toml         # Dependency management via `uv`
├── Dockerfile             # Container definition for production
├── docker-compose.yml     # Compose file for easy orchestration
├── function_app.py        # Azure Functions v2 entry point
├── host.json              # Azure Functions configuration
├── src/
│   └── mcp_ocr/
│       ├── api/           # FastAPI application and routing
│       ├── core/          # Configuration and settings management
│       ├── mcp/           # FastMCP server definition and tools
│       ├── services/      # Core business logic (RapidOCR integration)
│       └── main.py        # Entry points for CLI scripts
└── tests/                 # Unit, Integration, and MCP testing

Development & Quality Assurance

This project enforces strict code quality and security checks.

Run the Test Suite

uv run pytest

Run Linting & Formatting

uv run ruff check .
uv run ruff format .

Run Static Type Checking

uv run pyrefly check

Run Security Analysis

uv run bandit -c pyproject.toml -r src

CI/CD (GitHub Actions)

A fully automated CI/CD pipeline is provided in .github/workflows/azure-functions-deploy.yml. On every push to the main branch, the pipeline will:

  1. Setup Python and uv.
  2. Run code linting (ruff), security scans (bandit), and unit tests (pytest).
  3. Automatically export dependencies and deploy the application to your configured Azure Function App.

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Ensure all tests and linters pass (uv run pytest, uv run ruff check .)
  5. Push to the branch (git push origin feature/amazing-feature)
  6. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Ver o original no GitHub

Bom para

Relacionados