文件转换器 MCP 服务器

简体中文| English

此 MCP 服务器提供多种文件转换工具，用于转换各种文档和图像格式。该项目基于模型上下文协议 (MCP)构建，旨在服务于需要文件转换功能的 AI 代理。

特征

• DOCX 转 PDF ：将 Microsoft Word 文档转换为 PDF
• PDF 转 DOCX ：将 PDF 文档转换为 Microsoft Word 格式
• 图像格式转换：在各种图像格式（JPG、PNG、WebP 等）之间转换
• Excel 转 CSV ：将 Excel 电子表格转换为 CSV 格式
• HTML 转 PDF ：将 HTML 文件转换为 PDF 格式
• Markdown 转 PDF ：将 Markdown 文档转换为具有适当样式的 PDF
• 通用转换：一种尝试处理各种格式转换的多功能工具

技术

• Python 3.10+
• 模型上下文协议 (MCP) Python SDK
• 各种转换库：
  • docx2pdf - 用于 DOCX 到 PDF 的转换
  • pdf2docx - 用于 PDF 到 DOCX 的转换
  • Pillow - 用于图像格式转换
  • pandas - 用于 Excel 到 CSV 的转换
  • pdfkit - 用于 HTML 到 PDF 的转换
  • markdown - 用于将 Markdown 转换为 HTML

安装

1. 克隆存储库
   git clone https://github.com/wowyuarm/file-converter-mcp.git cd file-converter-mcp
2. 创建虚拟环境（可选但推荐）
   python -m venv venv source venv/bin/activate # On Unix-based systems venv\Scripts\activate # On Windows
3. 安装依赖项使用 pip 安装所需的软件包：
   pip install mcp docx2pdf pdf2docx pillow pandas pdfkit markdown
   或者，如果您使用uv ：
   uv add "mcp[cli]" docx2pdf pdf2docx pillow pandas pdfkit markdown
   注意：某些转换库可能需要额外的系统依赖项。请查看其文档了解详情。

用法

以开发模式运行服务器

要测试服务器，请运行：

安装 Claude Desktop

或者，您可以使用以下命令在 Claude Desktop 上安装服务器：

API / 工具

MCP 服务器公开以下工具：

基于路径的工具（也支持内容输入）

docx转pdf

命令： docx2pdf

• 输入选项 1 ：.docx 文件的路径
  input_file: path/to/document.docx
• 输入选项 2 ：DOCX 文件的 Base64 编码内容
  file_content_base64: [base64 encoded string]
• 输出：转换后的 PDF 文件的 Base64 编码字符串

pdf转docx

命令： pdf2docx

• 输入选项 1 ：PDF 文件的路径
  input_file: path/to/document.pdf
• 输入选项 2 ：PDF 文件的 Base64 编码内容
  file_content_base64: [base64 encoded string]
• 输出：转换后的 DOCX 文件的 Base64 编码字符串

转换图像

命令： convert_image

• 输入选项 1 ：
  input_file: path/to/image.png output_format: jpg
• 输入选项 2 ：
  file_content_base64: [base64 encoded string] input_format: png output_format: jpg
• 输出：转换后图像的 Base64 编码字符串

excel转csv

命令： excel2csv

• 输入：Excel 文件的路径（.xls 或 .xlsx）
• 输出：转换后的 CSV 文件的 Base64 编码字符串

html2pdf

命令： html2pdf

• 输入：HTML 或 Markdown 文件的路径（.html、.md、.markdown）
• 输出：转换后的 PDF 文件的 Base64 编码字符串

convert_file（通用转换器）

命令： convert_file

• 输入选项 1 ：
  input_file: path/to/file.docx input_format: docx output_format: pdf
• 输入选项 2 ：
  file_content_base64: [base64 encoded string] input_format: docx output_format: pdf
• 输出：转换文件的Base64编码字符串

基于内容的工具（遗留）

保留这些是为了向后兼容。现在所有主要工具都直接支持基于内容的输入。

convert_content（通用内容转换器）

命令： convert_content

• 输入：
  • 输入文件的 Base64 编码内容
  • 源格式（例如“docx”、“pdf”、“md”）
  • 目标格式（例如“pdf”、“docx”）
• 输出：转换文件的Base64编码字符串

docx2pdf_内容

命令： docx2pdf_content

• 输入：DOCX 文件的 Base64 编码内容
• 输出：转换后的 PDF 文件的 Base64 编码字符串

pdf2docx_内容

命令： pdf2docx_content

• 输入：PDF文件的Base64编码内容
• 输出：转换后的 DOCX 文件的 Base64 编码字符串

markdown2pdf_content

命令： markdown2pdf_content

• 输入：Markdown 文件的 Base64 编码内容
• 输出：转换后的 PDF 文件的 Base64 编码字符串

文件处理

该服务器包括强大的文件路径处理功能：

• 使用多阶段搜索策略来查找文件
• 在常见位置（临时目录、当前目录）搜索上传的文件
• 尝试多种文件名变体（不区分大小写，带/不带扩展名）
• 提供详细的日志以帮助解决文件位置问题
• 与通过 Claude 聊天界面上传的文件无缝协作
• 支持相对和绝对文件路径
• 尽可能自动检测文件格式

双模输入

所有转换工具现在都支持两种输入方法：

1. 基于路径的转换（传统方法）
   @File Converter docx2pdf input_file: file.docx
2. 基于内容的转换（即使路径查找失败也能工作）
   @File Converter docx2pdf file_content_base64: [base64 encoded string]

这种双模式方法提供了最大的灵活性和可靠性：

• 如有疑问，请使用基于内容的输入来保证处理
• 所有中间文件均在临时目录中以唯一名称创建
• 处理后会自动清理临时文件

处理特定于 Claude 的文件上传

与 Claude 一起使用时，如果文件上传失败：

1. 尝试使用带有前置路径的原始文件名：
   @File Converter docx2pdf input_file: /tmp/file.docx
2. 如果失败，请直接从 Claude 获取文件内容：
   @File Converter docx2pdf file_content_base64: [base64 content obtained from Claude]

错误处理

• 每个工具都使用多种搜索策略来验证文件的存在
• 详细的错误信息以结构化的JSON格式返回： {"success": false, "error": "error message"}
• 转换成功返回： {"success": true, "data": "base64 encoded file content"}
• 服务器包含全面的日志记录，用于故障排除
• 服务器优雅地处理异常并返回有用的错误消息

贡献

欢迎贡献！如果您想贡献，请遵循CONTRIBUTING.md中的指南（中文版：贡献指南，英语：贡献指南）。

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

GitHub 存储库

访问 GitHub 存储库： https://github.com/wowyuarm/file-converter-mcp