文件转换 MCP 服务器

这是一个用于在各种格式之间转换文件的模型上下文协议（MCP）服务器。

文件转换是一个设计用来处理广泛文件格式转换的MCP服务器，包括图像、办公文档、音频、视频、文本和数据文件。它旨在提供无缝转换到流行格式如PDF、JPG、MP4和HTML等。此服务器提供了一套强大的工具，可以将多种文件类型转换成易于访问且广泛兼容的格式，如PDF、JPG、PNG、TXT。

✨ 特性

• 智能文件类型检测： 结合使用AI、TrID和魔法字节进行准确的文件类型识别。
• 多功能文件转换： 支持在众多文件类型之间以及以下流行格式之间的转换：
  • 图像： 处理广泛的格式，包括许多遗留格式。转换为PDF、JPG、PNG。
  • 办公文档： 转换为PDF、TXT、HTML。
  • 音频/视频： 转换为MP3、MP4。
  • 数据库： 转换为CSV。
  • 其他文件： 提供其他文件类型的转换能力。

🛠️ 要求

1. Python： 需要版本3.12或更高版本。
2. uv 工具： 安装Python uv工具以实现高效的依赖管理及MCP服务器的轻松执行。
3. API密钥（开发阶段）： 截至2025年5月，MCP仍处于测试阶段，目前无需API密钥即可进行开发。对于未来的生产用途，请联系Convert.Guru团队获取API密钥。

🚀 桌面应用中的使用

要将此服务器与桌面应用程序集成，请在应用的服务器设置中添加以下配置。如有必要，请调整uv/uvx可执行文件（或Windows上的uv.exe/uvx.exe）的绝对路径。

使用uvx（推荐）：

{
  "mcpServers": {
    "file-convert": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/convertguru/file-convert-mcp.git", "file-convert-mcp"],
      "env": {
        "CONVERT_GURU_API_KEY": "your_api_key_here"
      }
    }
  }
}

如果您已本地克隆了仓库（根据需要调整路径）：

{
  "mcpServers": {
    "file--convert": {
      "command": "/home/User/.local/bin/uv",
      "args": ["--directory", "/home/User/file-convert-mcp/src/file_convert_mcp", "run", "server.py"],
      "env": {
        "CONVERT_GURU_API_KEY": "your_api_key_here"
      }
    }
  }
}

使用本地uvx：

{
  "mcpServers": {
    "file-convert": {
      "command": "uvx",
      "args": ["--from", "/home/User/file-convert-mcp", "file-convert-mcp"],
      "env": {
        "CONVERT_GURU_API_KEY": "your_api_key_here"
      }
    }
  }
}

环境变量

MCP服务器支持以下环境变量：

• CONVERT_GURU_API_KEY：您的Convert.Guru API密钥（开发阶段可选）
• TRANSPORT：MCP服务器的传输方法
  • "stdio"（默认）：标准输入/输出传输
  • "http"：HTTP传输（流式传输）带有REST API端点
• PORT：HTTP传输的端口号（默认：8000，仅当TRANSPORT=http时使用）

使用HTTP传输时，服务器提供额外的端点：

• GET /health - 健康检查端点
• GET /tools - 可用的MCP工具列表

另见如何在Claude Desktop上设置MCP工具的指南。

通过Smithery安装

要通过Smithery自动安装file-convert-mcp用于Claude Desktop：

npx -y @smithery/cli install @convertguru/file-convert-mcp --client claude

🛠️ 开发

按照以下步骤开始本地开发：

1. 克隆仓库：

git clone https://github.com/convertguru/file-convert-mcp.git

2. 获取并缓存Python依赖项（可选，uvx会自动处理）：

cd file-convert-mcp
uv sync
cd ..

3. 创建包含您的API密钥（目前可选）的.env文件：

echo "CONVERT_GURU_API_KEY=your_api_key_here" > file-convert-mcp/.env

4. 使用各种uv命令在本地运行MCP服务器：

# 使用来自本地目录的.env文件的uvx
cd file-convert-mcp
UV_ENV_FILE=.env uvx --from ./file-convert-mcp file-convert-mcp

# 或者直接使用uv运行服务器脚本
uv run file-convert-mcp/src/file_convert_mcp/server.py

# 或者指定uv的目录
uv --directory file-convert-mcp/src/file_convert_mcp run server.py

# 或者导航到服务器目录
cd file-convert-mcp/src/file_convert_mcp
uv run server.py

# 或者使用uvx从GitHub仓库获取核心+本地.env文件
UV_ENV_FILE=.env uvx --from git+https://github.com/convertguru/file-convert-mcp.git file-convert-mcp

# 或者在自定义端口上使用HTTP传输运行
TRANSPORT=http PORT=9000 uv run file-convert-mcp/src/file_convert_mcp/server.py

# 或者使用默认的stdio传输运行
TRANSPORT=stdio uv run file-convert-mcp/src/file_convert_mcp/server.py

5. 创建包含您配置的.env文件（目前可选）：

# 基本配置
echo "CONVERT_GURU_API_KEY=your_api_key_here" > file-convert-mcp/.env

# 或者带有传输配置
echo "CONVERT_GURU_API_KEY=your_api_key_here" > file-convert-mcp/.env
echo "TRANSPORT=http" >> file-convert-mcp/.env
echo "PORT=8000" >> file-convert-mcp/.env

6. 如需修改服务器逻辑： 编辑位于src/file_convert_mcp/server.py的主要服务器文件。

7. 清除uv缓存（如果需要）： 如果uv在~/.cache/uv中缓存了代码的旧版本，可能需要清除缓存。或者，使用uv的-n或--no-cache选项来绕过它。

⚙️ 可用工具

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

• detect_file_type：分析上传文件的前200个字节，并使用Convert.Guru API确定其类型。
• convert_file：将给定文件转换为指定的输出格式。应将所需的文件扩展名作为ext_out参数传递。

📜 许可证

访问我们 https://convert.guru

该项目基于MIT许可证——请参阅LICENSE文件以获取详细信息。