Skip to main content
Glama
irev

ReadPDFx - OCR PDF MCP Server

by irev
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

ReadPDFx - OCR PDF MCP Server

Official MCP SDK STDIO Server - MCP Protocol 2025-06-18 Compliant

MCP Protocol Python MCP SDK License

⚡ Quick Start (STDIO Server)

1. Install Dependencies

pip install -r requirements.txt

2. Validate Installation

# Test imports and tools python validate_tools.py

3. Client Integration

The server runs via STDIO protocol - configure your MCP client:

Claude Desktop:

{ "mcpServers": { "ocr-pdf": { "command": "python", "args": ["d:/AI/MCP/python/ocr_pdf_mcp/mcp_server_stdio.py"], "env": {} } } }

🚀 Features

  • 🎯 Official MCP SDK: Built with official FastMCP framework

  • 📡 STDIO Transport: Standard MCP protocol over STDIO

  • 🧠 Smart PDF Processing: Automatically detects digital vs scanned content

  • 🔧 5 OCR Tools: Text extraction, OCR processing, combined operations

  • 🌐 Universal Client Support: Claude Desktop, LM Studio, Continue.dev, Cursor

  • ⚡ Lightweight: ~200 lines vs 800+ in HTTP implementation

  • 🛡️ Production Ready: Comprehensive error handling and logging

  • 📋 Auto Tool Registration: Decorators handle tool discovery

🔧 Installation

Prerequisites

  • Python 3.8+

  • Tesseract OCR

Windows

# Install Python dependencies pip install -r requirements.txt # Install Tesseract choco install tesseract

macOS

pip install -r requirements.txt brew install tesseract

Linux

pip install -r requirements.txt sudo apt-get install tesseract-ocr

📋 Available Tools

1. Smart PDF Processing

Intelligent processing with automatic OCR detection:

{ "name": "process_pdf_smart", "arguments": { "pdf_path": "/path/to/document.pdf", "language": "eng" } }

2. PDF Text Extraction

Direct text extraction from digital PDFs:

{ "name": "extract_pdf_text", "arguments": { "pdf_path": "/path/to/document.pdf", "page_range": "1-5" } }

3. OCR Processing

OCR on image files:

{ "name": "perform_ocr", "arguments": { "image_path": "/path/to/image.png", "language": "eng" } }

4. PDF Structure Analysis

Analyze document structure and metadata:

{ "name": "analyze_pdf_structure", "arguments": { "pdf_path": "/path/to/document.pdf" } }

5. Batch Processing

Process multiple files:

{ "name": "batch_process_pdfs", "arguments": { "input_directory": "/path/to/pdfs/", "output_directory": "/path/to/output/", "file_pattern": "*.pdf" } }

🔌 Client Integration

Claude Desktop

Add to claude_desktop_config.json:

{ "mcpServers": { "readpdfx": { "command": "python", "args": ["path/to/readpdfx/run.py"], "env": { "PYTHONPATH": "path/to/readpdfx" } } } }

LM Studio

Configure MCP server with:

  • Command: python

  • Args: path/to/readpdfx/run.py

  • URL: http://localhost:8000 (HTTP mode)

Continue.dev

Add to config.json:

{ "contextProviders": [ { "name": "mcp", "params": { "command": "python", "args": ["path/to/readpdfx/run.py"] } } ] }

Cursor

Configure in settings.json:

{ "mcp.servers": { "readpdfx": { "command": "python", "args": ["path/to/readpdfx/run.py"] } } }

📁 See

🌐 API Endpoints

MCP Protocol Endpoints

  • POST /mcp/initialize - Initialize MCP session

  • POST /mcp/tools/list - List available tools

  • POST /mcp/tools/call - Call MCP tools

  • GET /mcp/manifest - Get MCP manifest

HTTP Endpoints

  • GET /health - Health check

  • POST /jsonrpc - JSON-RPC 2.0 endpoint

  • GET /docs - API documentation

  • GET /tools - Tools discovery

🔧 Configuration

Environment Variables

MCP_SERVER_HOST=localhost # Server host MCP_SERVER_PORT=8000 # Server port TESSERACT_CMD=/usr/bin/tesseract # Tesseract path PYTHONPATH=. # Python path

Config Files

  • mcp.json - MCP Protocol configuration

  • mcp-config.yaml - YAML configuration

  • pyproject.toml - Python project config

  • package.json - Node.js compatibility

🐳 Docker & Kubernetes

Docker Deployment

Quick Start with Docker

# Build and run with Docker docker build -t ocr-pdf-mcp . docker run -p 8000:8000 -v ./pdf-test:/app/pdf-test:ro ocr-pdf-mcp # Or use Docker Compose docker-compose up -d

Automated Docker Deployment

# Linux/macOS ./scripts/docker-deploy.sh run # Windows scripts\docker-deploy.bat run

Available Docker commands:

  • build - Build Docker image only

  • run - Build and run container (default)

  • start - Start container (assumes image exists)

  • stop - Stop running container

  • logs - Show container logs

  • clean - Stop container and remove image

  • status - Show container status

Kubernetes Deployment

Deploy to Kubernetes

# Quick deployment ./scripts/k8s-deploy.sh deploy # Manual deployment kubectl apply -f k8s/ -n ocr-pdf-mcp

Kubernetes Resources

  • Deployment: k8s/deployment.yaml - Main application deployment

  • Service: k8s/deployment.yaml - Service exposure

  • Ingress: k8s/ingress.yaml - External access

  • ConfigMap: k8s/configmap.yaml - Configuration management

  • HPA: k8s/hpa.yaml - Horizontal Pod Autoscaler

Kubernetes Commands

# Scale deployment kubectl scale deployment ocr-pdf-mcp --replicas=5 -n ocr-pdf-mcp # Port forward for local access kubectl port-forward svc/ocr-pdf-mcp-service 8000:80 -n ocr-pdf-mcp # View logs kubectl logs -f deployment/ocr-pdf-mcp -n ocr-pdf-mcp # Check status kubectl get pods,svc,ingress -n ocr-pdf-mcp

Production Considerations

Multi-stage Build

Use Dockerfile.prod for optimized production builds:

docker build -f Dockerfile.prod -t ocr-pdf-mcp:prod .

Environment Variables

# Docker docker run -e LOG_LEVEL=INFO -e CORS_ORIGINS="*" ocr-pdf-mcp # Kubernetes - update ConfigMap kubectl edit configmap ocr-pdf-mcp-config -n ocr-pdf-mcp

Persistent Storage

# Add to deployment.yaml volumeMounts: - name: pdf-storage mountPath: /app/pdf-test volumes: - name: pdf-storage persistentVolumeClaim: claimName: pdf-storage-pvc

🧪 Testing

Run Tests

python test_mcp_server.py

Manual Testing

# Health check curl http://localhost:8000/health # List tools curl -X POST http://localhost:8000/mcp/tools/list \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' # Call tool curl -X POST http://localhost:8000/mcp/tools/call \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "process_pdf_smart", "arguments": {"pdf_path": "/path/to/test.pdf"} }, "id": 1 }'

📊 Performance

  • Startup Time: < 2 seconds

  • Memory Usage: ~50MB base

  • Throughput: 10+ PDFs/minute

  • Concurrent Requests: Up to 100

  • File Size Limit: 100MB per file

🛠️ Development

Development Mode

python run_server.py --dev --port 8000

Project Structure

readpdfx/ ├── run.py # Simple production runner ├── run_server.py # Advanced runner with options ├── mcp_server.py # Core MCP server ├── mcp_tools.py # MCP tools implementation ├── mcp_types.py # MCP Protocol types ├── mcp_server_runner.py # HTTP server runner ├── client-configs/ # Client integration guides ├── backup/ # Legacy files └── tests/ # Test files

Adding New Tools

  1. Define tool schema in mcp_tools.py

  2. Implement tool handler method

  3. Register tool in MCPToolsRegistry

  4. Update tests and documentation

🐛 Troubleshooting

Common Issues

Server won't start

# Check port availability netstat -an | grep 8000 # Try different port python run_server.py --port 8001

OCR not working

# Check Tesseract installation tesseract --version # Install language data tesseract --list-langs

Permission errors

  • Ensure read access to PDF files

  • Check write permissions for output directory

  • Run with appropriate user privileges

Connection timeout

  • Verify server is running: curl http://localhost:8000/health

  • Check firewall settings

  • Try HTTP instead of direct MCP connection

Debug Mode

python run_server.py --dev

📈 Monitoring

Health Check

curl http://localhost:8000/health

Metrics (Future)

  • Request count and latency

  • Tool usage statistics

  • Error rates and types

  • Resource utilization

🤝 Contributing

  1. Fork the repository

  2. Create feature branch: git checkout -b feature/new-tool

  3. Make changes and add tests

  4. Submit pull request

Development Setup

git clone https://github.com/irev/mcp-readpdfx.git cd readpdfx pip install -r requirements-dev.txt python test_mcp_server.py

📄 License

MIT License - see LICENSE file.

🔗 Links

  • Repository: https://github.com/irev/mcp-readpdfx

  • Issues: https://github.com/irev/mcp-readpdfx/issues

  • Documentation: https://github.com/irev/mcp-readpdfx#readme

  • MCP Protocol: Model Context Protocol Specification

🏆 Acknowledgments

  • MCP Protocol Team for the specification

  • FastAPI for the web framework

  • Tesseract OCR for text recognition

  • PyPDF2 and pdfplumber for PDF processing

Made with ❤️ for the MCP community

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/irev/mcp-readpdfx'

If you have feedback or need assistance with the MCP directory API, please join our Discord server