Document Parser MCP
A Model Context Protocol (MCP) server that provides intelligent document parsing and conversion capabilities using the Docling toolkit. Convert any document (PDF, DOCX, images, audio, etc.) into clean Markdown for AI processing and RAG pipelines.
Features
- Universal Document Support: PDFs, Office documents (DOCX/XLSX/PPTX), images, HTML, Markdown, audio files, and more
- Multiple Processing Pipelines:
- Standard: Fast, high-quality conversion with advanced layout analysis
- VLM: Vision-language models for complex layouts and handwritten content
- ASR: Automatic speech recognition for audio transcription
- Intelligent Auto-Detection: Automatically selects optimal pipeline based on file type
- Concurrent Processing: Built-in job queue for handling multiple requests
- MCP Integration: Seamless integration with Claude Desktop and other MCP clients
- Clean Markdown Output: High-quality structured text ready for AI consumption
Installation
Prerequisites
- Python 3.9 or higher
- 8GB+ RAM recommended
Quick Start
- Clone the repository:
git clone <repository-url>
cd document-parser-mcp
- Create virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
- Install dependencies:
pip install -r requirements.txt
- Install Docling with optional features:
# Core Docling
pip install docling
# For Apple Silicon MLX acceleration
pip install docling[mlx]
# Optional OCR engines
pip install easyocr
Usage
Running the Server
Start the MCP server:
python -m document_parser
With custom configuration:
python -m document_parser --config /path/to/config.yaml
With debug logging:
python -m document_parser --debug
Configuration
The server is configured via config.yaml. Key settings:
server:
name: document-parser-mcp
max_concurrent_jobs: 3
job_timeout_seconds: 600
processing:
default_pipeline: standard
enable_pipeline_auto_detect: true
ocr:
engine: easyocr
languages: [eng]
pdf:
backend: dlparse_v4
table_accuracy_mode: accurate
See Configuration Guide for detailed options.
MCP Tools
The server provides the following MCP tools:
parse_document
Parse any document to Markdown.
Parameters:
source(required): File path or URL to the documentpipeline(optional): Processing pipeline -standard,vlm, orasroptions(optional): Additional processing options
Example:
{
"name": "parse_document",
"arguments": {
"source": "https://arxiv.org/pdf/2408.09869",
"pipeline": "standard"
}
}
parse_document_advanced
Advanced parsing with detailed configuration.
Parameters:
source(required): File path or URLpipeline(optional): Processing pipelineocr_enabled(optional): Enable/disable OCRtable_accuracy_mode(optional):fastoraccuratepdf_backend(optional): PDF processing backendenable_enrichments(optional): Enable code/formula enrichments
get_job_status
Get the status of a processing job.
Parameters:
job_id(required): Job identifier
list_supported_formats
List all supported input formats and pipelines.
get_queue_statistics
Get current queue and processing statistics.
Integration with Claude Desktop
Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"document-parser": {
"command": "python",
"args": ["-m", "document_parser"],
"cwd": "/path/to/document-parser-mcp"
}
}
}
Restart Claude Desktop and the document parser will be available as a tool.
Pipeline Selection Guide
Standard Pipeline (Default)
- Best for: Born-digital PDFs, Office documents, clean layouts
- Features: Advanced layout analysis, table structure recovery, optional OCR
- Performance: Fast, memory-efficient
VLM Pipeline
- Best for: Complex layouts, handwritten notes, screenshots, scanned documents
- Features: Vision-language model processing, end-to-end page understanding
- Performance: Slower, MLX-accelerated on Apple Silicon
ASR Pipeline
- Best for: Audio files (meetings, lectures, interviews)
- Features: Whisper-based transcription
- Performance: CPU/GPU intensive
Development
Running Tests
# Install development dependencies
pip install -r requirements-dev.txt
# Run tests
pytest
# Run with coverage
pytest --cov=document_parser
Code Quality
# Format code
black document_parser tests
# Lint
ruff check document_parser tests
# Type checking
mypy document_parser
Project Structure
document-parser-mcp/
├── document_parser/ # Main package
│ ├── config/ # Configuration system
│ ├── core/ # Core exceptions and types
│ ├── engine/ # Document processing engine
│ ├── mcp/ # MCP server implementation
│ ├── processing/ # Job queue and tracking
│ └── utils/ # Utility functions
├── tests/ # Test suite
├── config.yaml # Default configuration
├── requirements.txt # Production dependencies
└── setup.py # Package configuration
Performance Optimization
Memory Management
- Configure
max_memory_gbfor your system - Set
max_concurrent_jobsbased on available resources - Large files are processed with automatic cleanup
MLX Acceleration (Apple Silicon)
- Install with
pip install docling[mlx] - Enable in config:
enable_mlx_acceleration: true - Automatic fallback to CPU if unavailable
Troubleshooting
Common Issues
"ModuleNotFoundError: No module named 'docling'"
pip install docling
Queue is full errors
- Wait for current jobs to complete
- Increase
max_concurrent_jobsin config
Memory errors with large files
- Reduce
max_memory_gbin config - Use
pipeline: standardinstead ofvlm
OCR not working
pip install easyocr
# Or for tesseract
brew install tesseract # macOS
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Add tests for new functionality
- Run the test suite
- Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
MIT License - see LICENSE file for details.
Acknowledgments
- Built with Docling - an amazing document understanding toolkit
- Uses the Model Context Protocol for AI integration
Support
- Issues: GitHub Issues
- Documentation: Full Documentation