File Converter MCP Server

Features

• **DOCX to PDF**: Convert Microsoft Word documents to PDF

• **PDF to DOCX**: Convert PDF documents to Microsoft Word format

• **Image Format Conversion**: Convert between various image formats (JPG, PNG, WebP, etc.)

• **Excel to CSV**: Convert Excel spreadsheets to CSV format

• **HTML to PDF**: Convert HTML files to PDF format

• **Markdown to PDF**: Convert Markdown documents to PDF with proper styling

• **Generic Conversion**: A versatile tool that attempts to handle various format conversions

Technologies

• Python 3.10+

• [Model Context Protocol (MCP) Python SDK](https://pypi.org/project/mcp/)

• Various conversion libraries: - [docx2pdf](https://pypi.org/project/docx2pdf/) - for DOCX to PDF conversion - [pdf2docx](https://pypi.org/project/pdf2docx/) - for PDF to DOCX conversion - [Pillow](https://pypi.org/project/Pillow/) - for image format conversions - [pandas](https://pypi.org/project/pandas/) - for Excel to CSV conversion - [pdfkit](https://pypi.org/project/pdfkit/) - for HTML to PDF conversion - [markdown](https://pypi.org/project/markdown/) - for Markdown to HTML conversion

Installation

1. **Clone the Repository** ```bash git clone https://github.com/wowyuarm/file-converter-mcp.git cd file-converter-mcp ```

2. **Create a Virtual Environment (optional but recommended)** ```bash python -m venv venv source venv/bin/activate # On Unix-based systems venv\Scripts\activate # On Windows ```

3. **Install Dependencies** Install the required packages using pip: ```bash pip install mcp docx2pdf pdf2docx pillow pandas pdfkit markdown ``` Alternatively, if you are using [uv](https://docs.astral.sh/uv/): ```bash uv add "mcp[cli]" docx2pdf pdf2docx pillow pandas pdfkit markdown ``` Note: Some conversion libraries may have additional system dependencies. Please check their documentation for details.

Usage

Running the Server in Development Mode

Installing for Claude Desktop

API / Tools

Path-Based Tools (Also Support Content Input)

• **Input Option 1**: Path to a .docx file ``` input_file: path/to/document.docx ```

• **Input Option 2**: Base64 encoded content of the DOCX file ``` file_content_base64: [base64 encoded string] ```

• **Output**: Base64 encoded string of the converted PDF file

• **Input Option 1**: Path to a PDF file ``` input_file: path/to/document.pdf ```

• **Input Option 2**: Base64 encoded content of the PDF file ``` file_content_base64: [base64 encoded string] ```

• **Output**: Base64 encoded string of the converted DOCX file

• **Input Option 1**: ``` input_file: path/to/image.png output_format: jpg ```

• **Input Option 2**: ``` file_content_base64: [base64 encoded string] input_format: png output_format: jpg ```

• **Output**: Base64 encoded string of the converted image

• **Input**: Path to an Excel file (.xls or .xlsx)

• **Output**: Base64 encoded string of the converted CSV file

• **Input**: Path to an HTML or Markdown file (.html, .md, .markdown)

• **Output**: Base64 encoded string of the converted PDF file

• **Input Option 1**: ``` input_file: path/to/file.docx input_format: docx output_format: pdf ```

• **Input Option 2**: ``` file_content_base64: [base64 encoded string] input_format: docx output_format: pdf ```

• **Output**: Base64 encoded string of the converted file

Content-Based Tools (Legacy)

• **Input**: - Base64 encoded content of the input file - Source format (e.g., "docx", "pdf", "md") - Target format (e.g., "pdf", "docx")

• **Output**: Base64 encoded string of the converted file

• **Input**: Base64 encoded content of the DOCX file

• **Output**: Base64 encoded string of the converted PDF file

• **Input**: Base64 encoded content of the PDF file

• **Output**: Base64 encoded string of the converted DOCX file

• **Input**: Base64 encoded content of the Markdown file

• **Output**: Base64 encoded string of the converted PDF file

File Handling

• Uses a multi-stage search strategy to find files

• Searches for uploaded files in common locations (temp directories, current directory)

• Tries multiple filename variations (case-insensitive, with/without extensions)

• Provides detailed logs to help troubleshoot file location issues

• Works seamlessly with files uploaded via Claude chat interface

• Supports relative and absolute file paths

• Automatically detects file formats when possible

Dual-Mode Input

1. **Path-Based Conversion** (traditional approach) ``` @File Converter docx2pdf input_file: file.docx ```

2. **Content-Based Conversion** (works even when path lookup fails) ``` @File Converter docx2pdf file_content_base64: [base64 encoded string] ```

• When in doubt, use content-based input for guaranteed processing

• All intermediate files are created with unique names in temporary directories

• Temporary files are automatically cleaned up after processing

Handling Claude-Specific File Uploads

1. Try using the original filename with a preceding path: ``` @File Converter docx2pdf input_file: /tmp/file.docx ```

2. If that fails, obtain the file content directly from Claude: ``` @File Converter docx2pdf file_content_base64: [base64 content obtained from Claude] ```

Error Handling

• Each tool validates file existence using multiple search strategies

• Detailed error messages are returned in a structured JSON format: `{"success": false, "error": "error message"}`

• Successful conversions return: `{"success": true, "data": "base64 encoded file content"}`

• The server includes comprehensive logging for troubleshooting

• The server gracefully handles exceptions and returns informative error messages

Contributing

License

GitHub Repository