File Convert MCP Server

File Convert MCP サーバー

さまざまな形式のファイルを変換するための 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 ツール： 効率的な依存関係管理と MCP サーバーの簡単な実行のため、Python uv tool をインストールしてください。
3. API キー（開発用）： 2025 年 5 月現在、MCP はテスト段階にあり、開発時に API キーは不要です。今後の本番環境での利用に向けて API キーを取得するには、Convert.Guru チームにお問い合わせください。

🚀 デスクトップアプリでの使用

このサーバーをデスクトップアプリに統合するには、アプリのサーバー設定に以下の構成を追加してください。必要に応じて、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.（現時点では省略可能な）API キーを含む .env ファイルを作成します：

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 に古いコードのバージョンをキャッシュしている場合は、キャッシュをクリアする必要があることがあります。または、-n あるいは --no-cache オプションを付けて uv を実行すると、キャッシュを回避できます。

⚙️ 利用可能なツール

MCP サーバーでは、以下のツールを利用できます。

• detect_file_type：アップロードされたファイルの先頭 200 バイトを分析し、Convert.Guru API を使用してファイルの種類を判定します。
• convert_file：指定したファイルを指定の出力形式に変換します。希望するファイル拡張子は ext_out パラメーターとして渡してください。

📜 ライセンス

https://convert.guru にアクセスしてください。

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については LICENSE ファイルをご覧ください。