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

1. Clone the repository:

git clone <repository-url>
cd document-parser-mcp

2. Create virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. 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 document
• pipeline (optional): Processing pipeline - standard, vlm, or asr
• options (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 URL
• pipeline (optional): Processing pipeline
• ocr_enabled (optional): Enable/disable OCR
• table_accuracy_mode (optional): fast or accurate
• pdf_backend (optional): PDF processing backend
• enable_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_gb for your system
• Set max_concurrent_jobs based 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_jobs in config

Memory errors with large files

• Reduce max_memory_gb in config
• Use pipeline: standard instead of vlm

OCR not working

pip install easyocr
# Or for tesseract
brew install tesseract  # macOS

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. 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