文件转换器 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      # 在基于 Unix 的系统上
   venv\Scripts\activate         # 在 Windows 上
   

3. 安装依赖

   使用 pip 安装所需的包:

   pip install mcp docx2pdf pdf2docx pillow pandas pdfkit markdown
   

   或者，如果您使用 uv:

   uv add "mcp[cli]" docx2pdf pdf2docx pillow pandas pdfkit markdown
   

   注意: 某些转换库可能具有额外的系统依赖项。请查看它们的文档以获取详细信息。

使用

在开发模式下运行服务器

要测试服务器，请运行:

mcp dev file_converter_server.py

为 Claude Desktop 安装

可选地，您可以使用以下命令在 Claude Desktop 上安装服务器:

mcp install file_converter_server.py --name "File Converter"

API / 工具

MCP 服务器公开以下工具:

基于路径的工具 (也支持内容输入)

docx2pdf

命令: docx2pdf

• 输入选项 1: .docx 文件的路径

  input_file: path/to/document.docx
  

• 输入选项 2: DOCX 文件的 Base64 编码内容

  file_content_base64: [base64 encoded string]
  

• 输出: 转换后的 PDF 文件的 Base64 编码字符串

pdf2docx

命令: pdf2docx

• 输入选项 1: PDF 文件的路径

  input_file: path/to/document.pdf
  

• 输入选项 2: PDF 文件的 Base64 编码内容

  file_content_base64: [base64 encoded string]
  

• 输出: 转换后的 DOCX 文件的 Base64 编码字符串

convert_image

命令: 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 编码字符串

excel2csv

命令: 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_content

命令: docx2pdf_content

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

pdf2docx_content

命令: 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: [从 Claude 获取的 base64 内容]
   

错误处理

• 每个工具都使用多种搜索策略验证文件是否存在
• 详细的错误消息以结构化的 JSON 格式返回: {"success": false, "error": "错误消息"}
• 成功的转换返回: {"success": true, "data": "base64 编码的文件内容"}
• 该服务器包括用于故障排除的全面日志记录
• 该服务器可以优雅地处理异常并返回信息丰富的错误消息

贡献

欢迎贡献! 如果您想贡献，请遵循 CONTRIBUTING.md 中的指南 (中文版: 贡献指南, English: Contributing Guidelines).

许可证

该项目已获得 MIT 许可证的许可 – 有关详细信息，请参阅 LICENSE 文件。

GitHub 仓库

访问 GitHub 仓库: https://github.com/wowyuarm/file-converter-mcp