Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ReadPDFx - OCR PDF MCP Serverextract 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
โก Quick Start (STDIO Server)
1. Install Dependencies
pip install -r requirements.txt2. Validate Installation
# Test imports and tools
python validate_tools.py3. 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 tesseractmacOS
pip install -r requirements.txt
brew install tesseractLinux
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:
pythonArgs:
path/to/readpdfx/run.pyURL:
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 client-configs/ for detailed integration guides.
๐ API Endpoints
MCP Protocol Endpoints
POST /mcp/initialize- Initialize MCP sessionPOST /mcp/tools/list- List available toolsPOST /mcp/tools/call- Call MCP toolsGET /mcp/manifest- Get MCP manifest
HTTP Endpoints
GET /health- Health checkPOST /jsonrpc- JSON-RPC 2.0 endpointGET /docs- API documentationGET /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 pathConfig Files
mcp.json- MCP Protocol configurationmcp-config.yaml- YAML configurationpyproject.toml- Python project configpackage.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 -dAutomated Docker Deployment
# Linux/macOS
./scripts/docker-deploy.sh run
# Windows
scripts\docker-deploy.bat runAvailable Docker commands:
build- Build Docker image onlyrun- Build and run container (default)start- Start container (assumes image exists)stop- Stop running containerlogs- Show container logsclean- Stop container and remove imagestatus- Show container status
Kubernetes Deployment
Deploy to Kubernetes
# Quick deployment
./scripts/k8s-deploy.sh deploy
# Manual deployment
kubectl apply -f k8s/ -n ocr-pdf-mcpKubernetes Resources
Deployment:
k8s/deployment.yaml- Main application deploymentService:
k8s/deployment.yaml- Service exposureIngress:
k8s/ingress.yaml- External accessConfigMap:
k8s/configmap.yaml- Configuration managementHPA:
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-mcpProduction 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-mcpPersistent 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.pyManual 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 8000Project 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 filesAdding New Tools
Define tool schema in
mcp_tools.pyImplement tool handler method
Register tool in
MCPToolsRegistryUpdate 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 8001OCR not working
# Check Tesseract installation
tesseract --version
# Install language data
tesseract --list-langsPermission 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/healthCheck firewall settings
Try HTTP instead of direct MCP connection
Debug Mode
python run_server.py --dev๐ Monitoring
Health Check
curl http://localhost:8000/healthMetrics (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-toolMake 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
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.