File Convert MCP Server

File Convert MCP Server

用于在各种格式之间转换文件的 Model Context Protocol（MCP）服务。

File Convert 是一款 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"：带 REST API 端点的 HTTP（流式）传输
• PORT：HTTP 传输的端口号（默认值：8000，仅在 TRANSPORT=http 时使用）

使用 HTTP 传输时，服务会提供其他端点：

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

另请参阅此指南，了解如何在 Claude Desktop 中设置 MCP 工具。

通过 Smithery 安装

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

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. 创建 .env 文件并填入你的 API 密钥（目前可选）：

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

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

# Using uvx with .env file from the local directory
cd file-convert-mcp
UV_ENV_FILE=.env uvx --from ./file-convert-mcp file-convert-mcp

# OR using uv directly to run the server script
uv run file-convert-mcp/src/file_convert_mcp/server.py

# OR specifying the directory for uv
uv --directory file-convert-mcp/src/file_convert_mcp run server.py

# OR navigating into the server directory
cd file-convert-mcp/src/file_convert_mcp
uv run server.py

# OR using uvx to fetch the core from the GitHub repository + local .env file
UV_ENV_FILE=.env uvx --from git+https://github.com/convertguru/file-convert-mcp.git file-convert-mcp

# OR run with HTTP transport on custom port
TRANSPORT=http PORT=9000 uv run file-convert-mcp/src/file_convert_mcp/server.py

# OR run with stdio transport (default)
TRANSPORT=stdio uv run file-convert-mcp/src/file_convert_mcp/server.py

5. 创建 .env 文件并填入你的配置（目前可选）：

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

# OR with transport configuration
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 选项绕过缓存。

⚙️ 可用工具

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

📜 许可证

欢迎访问我们的网站 https://convert.guru

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。