File Converter MCP Server
简体中文 | English
This MCP server provides multiple file conversion tools for converting various document and image formats. This project is built using the Model Context Protocol (MCP) and is designed to serve AI agents that need file conversion capabilities.
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
Installation
Clone the Repository
git clone https://github.com/wowyuarm/file-converter-mcp.git
cd file-converter-mcp
Create a Virtual Environment (optional but recommended)
python -m venv venv
source venv/bin/activate # On Unix-based systems
venv\Scripts\activate # On Windows
- Install Dependencies
Install the required packages using pip:
pip install mcp docx2pdf pdf2docx pillow pandas pdfkit markdown
Alternatively, if you are using uv:
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
To test the server, run:
mcp dev file_converter_server.py
Installing for Claude Desktop
Optionally, you can install the server on Claude Desktop with:
mcp install file_converter_server.py --name "File Converter"
API / Tools
The MCP server exposes the following tools:
Path-Based Tools (Also Support Content Input)
docx2pdf
Command: docx2pdf
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
pdf2docx
Command: pdf2docx
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
convert_image
Command: convert_image
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
excel2csv
Command: excel2csv
- Input : Path to an Excel file (.xls or .xlsx)
- Output : Base64 encoded string of the converted CSV file
html2pdf
Command: html2pdf
- Input : Path to an HTML or Markdown file (.html, .md, .markdown)
- Output : Base64 encoded string of the converted PDF file
convert_file (Generic Converter)
Command: convert_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)
These are maintained for backward compatibility. All main tools now support content-based input directly.
convert_content (Generic Content Converter)
Command: convert_content
- 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
docx2pdf_content
Command: docx2pdf_content
- Input : Base64 encoded content of the DOCX file
- Output : Base64 encoded string of the converted PDF file
pdf2docx_content
Command: pdf2docx_content
- Input : Base64 encoded content of the PDF file
- Output : Base64 encoded string of the converted DOCX file
markdown2pdf_content
Command: markdown2pdf_content
- Input : Base64 encoded content of the Markdown file
- Output : Base64 encoded string of the converted PDF file
File Handling
The server includes robust file path handling that:
- 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
All conversion tools now support two methods of input:
Path-Based Conversion (traditional approach)
@File Converter
docx2pdf
input_file: file.docx
Content-Based Conversion (works even when path lookup fails)
@File Converter
docx2pdf
file_content_base64: [base64 encoded string]
This dual-mode approach provides maximum flexibility and reliability:
- 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
When using with Claude, if a file upload fails to be found:
Try using the original filename with a preceding path:
@File Converter
docx2pdf
input_file: /tmp/file.docx
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
Contributions are welcome! If you'd like to contribute, please follow the guidelines in CONTRIBUTING.md (中文版: 贡献指南, English: Contributing Guidelines).
License
This project is licensed under the MIT License – see the LICENSE file for details.
GitHub Repository
Visit the GitHub repository at: https://github.com/wowyuarm/file-converter-mcp
