星战科技xingzhan.cloud
返回市场
文件转换器_mCP

文件转换器_mCP

作者：wowyuarm23 星标更新：2025-06-21
安装使用来源：spider==github.com

项目介绍

文件转换器 MCP 服务器

简体中文 | English

License: MIT Python 3.10+

此 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
  • 通用转换: 一种多功能工具，尝试处理各种格式转换

技术栈

安装

  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 编码字符串]
  • 输出：转换后的 PDF 文件的 Base64 编码字符串
pdf2docx

命令：pdf2docx

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

命令：convert_image

  • 输入选项 1： 
    input_file: path/to/image.png
output_format: jpg
  • 输入选项 2： 
    file_content_base64: [Base64 编码字符串]
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 编码字符串]
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. 基于路径的转换（传统方法）

    @文件转换器
docx2pdf
input_file: file.docx

  2. 基于内容的转换（即使路径查找失败也能工作）

    @文件转换器
docx2pdf
file_content_base64: [Base64 编码字符串]

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

  • 当不确定时，使用基于内容的输入以保证处理
  • 所有中间文件都在临时目录中创建，并具有唯一名称
  • 处理完成后自动清理临时文件

处理 Claude 特定文件上传

当与 Claude 一起使用时，如果文件上传无法找到：

  1. 尝试使用带有前缀路径的原始文件名：

    @文件转换器
docx2pdf
input_file: /tmp/file.docx

  2. 如果这不起作用，直接从 Claude 获取文件内容：

    @文件转换器
docx2pdf
file_content_base64: [从 Claude 获取的 Base64 内容]

错误处理

  • 每个工具使用多种搜索策略验证文件存在性
  • 返回结构化的 JSON 格式的详细错误消息：{"success": false, "error": "错误消息"}
  • 成功转换返回：{"success": true, "data": "Base64 编码的文件内容"}
  • 服务器包含全面的日志以帮助排查问题
  • 服务器优雅地处理异常并返回信息性的错误消息

贡献

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

许可证

本项目根据 MIT 许可证发布 - 详情见 LICENSE 文件。

GitHub 仓库

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

MCP 服务器配置

此项目可用作模型上下文协议（MCP）服务器，为 AI 代理提供文件转换工具。

快速开始

  1. 安装依赖项：

    python -m pip install -e .

  2. 启动 MCP 服务器：

    python start_mcp_server.py

  3. 配置您的 MCP 客户端（例如 Claude Desktop、Cursor），使用以下配置：

    推荐配置（cursor-mcp.config.json）：

    {
  "mcpServers": {
    "file-converter": {
      "command": "python",
      "args": ["file_converter_server.py"],
      "cwd": "."
    }
  }
}

    替代配置（mcp.config.json）：

    {
  "mcpServers": {
    "file-converter": {
      "command": "python",
      "args": ["file_converter_server.py"],
      "cwd": "."
    }
  }
}

重要说明

  • 建议使用 stdio 模式 - 这是连接 MCP 服务器最可靠的方式
  • 使用 cursor-mcp.config.json 以获得最简单的配置
  • 确保服务器正在运行，然后再从 Cursor 连接

可用工具

MCP 服务器提供了以下工具：

  • docx2pdf: 将 Word 文档转换为 PDF
  • pdf2docx: 将 PDF 转换为 Word 文档
  • convert_image: 在图像格式之间进行转换（如 PNG、JPG、WEBP 等）
  • excel2csv: 将 Excel 文件转换为 CSV
  • html2pdf: 将 HTML/Markdown 转换为 PDF
  • convert_file: 在支持的格式之间进行通用文件转换
  • convert_content: 从 Base64 内容转换文件

使用示例

一旦配置好，您可以在您的 AI 代理中使用这些工具：

将这个 Word 文档转换为 PDF: [上传文件]
将这个图像从 PNG 转换为 JPG: [上传文件]
将这个 Excel 文件转换为 CSV: [上传文件]