Mcp Document Converter

MCP Document Converter

MCP (Model Context Protocol) Document Converter - A powerful MCP tool for converting documents between multiple formats, enabling AI agents to easily transform documents.

🌐 Language: English | 中文

[CSDN] [GitHub] [Gitee]

[License] [Python] [PyPI Version] [PyPI Downloads] [MCP Registry] [MCP Marketplace]

Features

• Multi-format Support: Supports 5 mainstream document formats: Markdown, HTML, DOCX, PDF, and Text
• Bidirectional Conversion: Any format can be converted to any other format (5×5=25 conversion combinations)
• MCP Protocol: Compliant with MCP standards, can be used as a tool for AI assistants like Trae IDE
• Plugin Architecture: Easy to extend with new parsers and renderers
• Syntax Highlighting: HTML and PDF outputs support code syntax highlighting
• Style Customization: Support for custom CSS styles
• Metadata Preservation: Preserves document title, author, creation time, and other metadata during conversion

📚 Documentation

User Guide · API Reference · Contributing · Changelog · License

Architecture

flowchart TB    subgraph Parsers["Parsers"]        MD[Markdown]        DOCX1[DOCX]        HTML1[HTML]        PDF1[PDF]        TXT1[Text]    end
    subgraph IR["Intermediate Representation (IR)"]        DT[Document Tree]        META[Metadata]        ASSETS[Assets]    end
    subgraph Renderers["Renderers"]        HTML2[HTML]        PDF2[PDF]        MD2[Markdown]        DOCX2[DOCX]        TXT2[Text]    end
    MD --> IR    DOCX1 --> IR    HTML1 --> IR    PDF1 --> IR    TXT1 --> IR        IR --> HTML2    IR --> PDF2    IR --> MD2    IR --> DOCX2    IR --> TXT2

Core Components

1. DocumentIR (Intermediate Representation): Unified abstraction for all documents, containing document tree, metadata, assets, etc.
2. BaseParser (Parser Base Class): Defines the parser interface, parses various formats into DocumentIR
3. BaseRenderer (Renderer Base Class): Defines the renderer interface, renders DocumentIR into various formats
4. ConverterRegistry (Registry): Manages all parsers and renderers, provides format lookup and auto-matching
5. DocumentConverter (Conversion Engine): Coordinates parsers and renderers to complete document conversion

Supported Formats

Input Formats (Parsers)

Output Formats (Renderers)

Conversion Matrix

flowchart LR    subgraph Sources["Source Formats"]        MD_S[Markdown]        HTML_S[HTML]        DOCX_S[DOCX]        PDF_S[PDF]        TXT_S[Text]    end
    subgraph Targets["Target Formats"]        MD_T[Markdown]        HTML_T[HTML]        DOCX_T[DOCX]        PDF_T[PDF]        TXT_T[Text]    end
    MD_S --> Targets    HTML_S --> Targets    DOCX_S --> Targets    PDF_S --> Targets    TXT_S --> Targets

Installation

Using pip (Recommended)

pip install mcp-document-converter

From Source

git clone https://github.com/xt765/mcp-document-converter.gitcd mcp-document-converterpip install -e .

MCP Tools

This server provides the following tools:

convert_document

Convert a document from one format to another.

Arguments:

• source_path (string, required): Path to the source document.
• target_format (string, required): Target format (html, pdf, markdown, docx, text).
• output_path (string, optional): Path for the output file.
• source_format (string, optional): Format of the source file (auto-detected if not provided).
• options (object, optional): Additional options like template, css, and preserve_metadata.

Configuration

Using in Trae IDE / Claude Desktop

Add the following to your MCP configuration file:

Option 1: Using PyPI (Recommended)

{  "mcpServers": {    "mcp-document-converter": {      "command": "uvx",      "args": [        "mcp-document-converter"      ]    }  }}

Option 2: Using GitHub repository

{  "mcpServers": {    "mcp-document-converter": {      "command": "uvx",      "args": [        "--from",        "git+https://github.com/xt765/mcp-document-converter",        "mcp-document-converter"      ]    }  }}

Option 3: Using Gitee repository (Faster access in China)

{  "mcpServers": {    "mcp-document-converter": {      "command": "uvx",      "args": [        "--from",        "git+https://gitee.com/xt765/mcp-document-converter",        "mcp-document-converter"      ]    }  }}

Option 4: Using pip (Manual installation)

First install the package:

pip install mcp-document-converter

Then add to configuration:

{  "mcpServers": {    "mcp-document-converter": {      "command": "mcp-document-converter",      "args": []    }  }}

Using in Cherry Studio

Cherry Studio is a powerful open-source desktop AI client assistant that supports integrating various tools through the MCP protocol

Configuration Example:

[Cherry Studio Configuration]

Usage Example:

[Cherry Studio Usage]

Usage

As an MCP Tool

After configuration, AI assistants can directly call the following tools:

1. convert_document (Recommended)

Use a unified interface to convert any supported document type.

# Markdown to HTMLconvert_document(    source_path="document.md",    target_format="html")
# HTML to PDFconvert_document(    source_path="document.html",    target_format="pdf")
# DOCX to Markdownconvert_document(    source_path="document.docx",    target_format="markdown")
# Conversion with optionsconvert_document(    source_path="document.md",    target_format="html",    output_path="output.html",    options={        "css": "custom.css",        "preserve_metadata": True    })

2. list_supported_formats

List all supported document formats.

list_supported_formats()

3. get_conversion_matrix

Get the complete format conversion matrix.

get_conversion_matrix()

4. can_convert

Check if conversion from source format to target format is supported.

can_convert(source_format="markdown", target_format="pdf")

5. get_format_info

Get detailed information about a specific format.

get_format_info(format="markdown")

As a Python Library

from mcp_document_converter import DocumentConverterfrom mcp_document_converter.registry import get_registryfrom mcp_document_converter.parsers import MarkdownParser, HTMLParserfrom mcp_document_converter.renderers import HTMLRenderer, PDFRenderer
# Register parsers and renderersregistry = get_registry()registry.register_parser(MarkdownParser())registry.register_parser(HTMLParser())registry.register_renderer(HTMLRenderer())registry.register_renderer(PDFRenderer())
# Create converterconverter = DocumentConverter(registry)
# Convert documentresult = converter.convert(    source="input.md",    target_format="html",    output_path="output.html")
if result.success:    print(f"✅ Conversion successful: {result.output_path}")else:    print(f"❌ Conversion failed: {result.error_message}")

Tool Interface Details

convert_document

Convert a document from one format to another.

Parameters:

Options:

Example:

{  "source_path": "/path/to/document.md",  "target_format": "html",  "output_path": "/path/to/output.html",  "options": {    "css": "body { font-family: Arial; }",    "preserve_metadata": true  }}

Extension Development

Adding a New Parser

from typing import List, Unionfrom pathlib import Pathfrom mcp_document_converter.core.parser import BaseParserfrom mcp_document_converter.core.ir import DocumentIR, Node, NodeType
class MyParser(BaseParser):    @property    def supported_extensions(self) -> List[str]:        return [".myext"]        @property    def format_name(self) -> str:        return "myformat"        @property    def mime_types(self) -> List[str]:        return ["application/x-myformat"]        def parse(self, source: Union[str, Path, bytes], **options) -> DocumentIR:        # Read source file        content = self._read_source(source)                # Parse into DocumentIR        document = DocumentIR()        document.title = "My Document"                # Add content nodes        document.add_node(Node(            type=NodeType.PARAGRAPH,            content=[Node(type=NodeType.TEXT, content="Hello World")]        ))                return document

Adding a New Renderer

from typing import Anyfrom mcp_document_converter.core.renderer import BaseRendererfrom mcp_document_converter.core.ir import DocumentIR
class MyRenderer(BaseRenderer):    @property    def output_extension(self) -> str:        return ".myext"        @property    def format_name(self) -> str:        return "myformat"        @property    def mime_type(self) -> str:        return "application/x-myformat"        def render(self, document: DocumentIR, **options: Any) -> str:        # Render DocumentIR to target format        parts = []                if document.title:            parts.append(f"# {document.title}")                for node in document.content:            # Render each node            pass                return "\n".join(parts)

Registering Extensions

from mcp_document_converter.registry import get_registry
# Register new parser and rendererregistry = get_registry()registry.register_parser(MyParser())registry.register_renderer(MyRenderer())

Testing

# Run all testspython tests/test_conversion.py
# Run specific testpython tests/test_conversion.py::test_markdown_to_html

Environment Variables

Dependencies

Core Dependencies

• mcp >= 1.26.0 - MCP protocol implementation
• pydantic >= 2.12.5 - Data validation

Parser Dependencies

• markdown >= 3.5.0 - Markdown parsing
• beautifulsoup4 >= 4.12.0 - HTML parsing
• python-docx >= 1.1.0 - DOCX parsing
• pypdf >= 6.7.4 - PDF parsing
• chardet >= 5.0.0 - Encoding detection
• pyyaml >= 6.0.0 - YAML parsing

Renderer Dependencies

• weasyprint >= 60.0 - PDF rendering
• pygments >= 2.17.0 - Code highlighting
• jinja2 >= 3.1.6 - Template engine
• reportlab >= 4.0.0 - PDF generation

Development Dependencies

• pytest >= 7.0.0 - Testing framework
• pytest-asyncio >= 0.21.0 - Async testing support
• pytest-cov >= 4.0.0 - Coverage reporting
• basedpyright >= 1.0.0 - Type checking
• ruff >= 0.1.0 - Linting and formatting

License

MIT License

Contributing

Issues and Pull Requests are welcome!

Related Projects

• MCP Document Reader - MCP document reader supporting multiple document formats
• Model Context Protocol - Official Model Context Protocol documentation