How do I use ReadPDFx - OCR PDF MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ReadPDFx - OCR PDF MCP Server extract text from the scanned contract.pdf in English" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

Define tool schema in mcp_tools.py
Implement tool handler method
Register tool in MCPToolsRegistry
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

Fork the repository
Create feature branch: git checkout -b feature/new-tool
Make changes and add tests
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

license - permissive license

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Related Servers

ReadPDFx - OCR PDF MCP Server

⚡ Quick Start (STDIO Server)

1. Install Dependencies

2. Validate Installation

3. Client Integration

🚀 Features

🔧 Installation

Prerequisites

Windows

macOS

Linux

📋 Available Tools

1. Smart PDF Processing

2. PDF Text Extraction

3. OCR Processing

4. PDF Structure Analysis

5. Batch Processing

🔌 Client Integration

Claude Desktop

LM Studio

Continue.dev

Cursor

🌐 API Endpoints

MCP Protocol Endpoints

HTTP Endpoints

🔧 Configuration

Environment Variables

Config Files

🐳 Docker & Kubernetes

Docker Deployment

Quick Start with Docker

Automated Docker Deployment

Kubernetes Deployment

Deploy to Kubernetes

Kubernetes Resources

Kubernetes Commands

Production Considerations

Multi-stage Build

Environment Variables

Persistent Storage

🧪 Testing

Run Tests

Manual Testing

📊 Performance

🛠️ Development

Development Mode

Project Structure

Adding New Tools

🐛 Troubleshooting

Common Issues

Debug Mode

📈 Monitoring

Health Check

Metrics (Future)

🤝 Contributing

Development Setup

📄 License

🔗 Links

🏆 Acknowledgments

Resources

Appeared in Searches

Latest Blog Posts

MCP directory API