MLX Whisper MCP Server

MLX Whisper MCP Server

Apple Silicon Mac 上で MLX Whisper を使用し、音声の文字起こし機能を提供するシンプルな Model Context Protocol（MCP）サーバーです。

Features

• ディスク上の音声ファイルを直接文字起こしします
• Base64 エンコードされたデータから音声を文字起こしします
• YouTube 動画をダウンロードして文字起こしします
• 高品質な mlx-community/whisper-large-v3-turbo モデルを使用します
• uv run による依存関係の自動管理に対応した、単独で実行できるスクリプトです
• デバッグしやすいリッチなコンソール出力を備えています
• 音声ファイルと同じ場所に文字起こしテキストファイルを保存します

Requirements

• Python 3.12 以降
• Apple Silicon Mac（M シリーズ）
• uv がインストールされていること（pip install uv または curl -sS https://astral.sh/uv/install.sh | bash）

Quick Start

uv run で直接実行します。

uv run mlx_whisper_mcp.py

これだけです！スクリプトが依存関係を自動的にインストールし、MCP サーバーを起動します。 注：初回実行時は Whisper モデル（約 1.6GB）をダウンロードするため、起動に時間がかかることがあります。2 回目以降はより速く起動します。

Using with Claude Desktop

このサーバーを Claude Desktop に統合する主な方法は 2 つあります。

Option 1: Using uv (Recommended)

1. mlx_whisper_mcp.py をクローンまたは保存したディレクトリに移動します。
2. 次のコマンドを実行します。

   uv tool run fastmcp install mlx_whisper_mcp.py
   

3. Claude Desktop を起動している場合は、再起動します。fastmcp がサーバーの起動に必要な設定を行い、依存関係も uv run で管理します。

Option 2: Manual Configuration

Claude Desktop を手動で設定する場合：

1. Claude Desktop の設定ファイルを編集します。

   # On macOS:
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # On Windows:
   code %APPDATA%\Claude\claude_desktop_config.json
   

2. MLX Whisper MCP サーバーの設定を追加します。 重要： 以下の cwd フィールドにある /absolute/path/to/mlx_whisper_mcp/ を、お使いのシステム上で mlx_whisper_mcp.py を含むディレクトリの実際の絶対パスに置き換えてください。

   {
     "mcpServers": {
       "mlx-whisper": {
         "command": "uv",
         "args": [
           "run",
           "mlx_whisper_mcp.py"
         ],
         "cwd": "/absolute/path/to/mlx_whisper_mcp/"
       }
     }
   }
   

   この設定により、Claude Desktop は uv run を使用して mlx_whisper_mcp.py を実行し、現在の作業ディレクトリ（cwd）をスクリプトの場所に設定します。uv run がスクリプトに定義された依存関係のインストールを処理します。

3. Claude Desktop を再起動します。

Available Tools

サーバーは次のツールを提供します。

1. transcribe_file

ディスク上のパスを指定して、音声ファイルを文字起こしします。

Parameters:

• file_path：音声ファイルのパス
• language：（任意）特定の言語を指定する言語コード
• task："transcribe" または "translate"（英語に翻訳します）

2. transcribe_audio

Base64 エンコードされたデータから音声を文字起こしします。

Parameters:

• audio_data：Base64 エンコードされた音声データ
• language：（任意）特定の言語を指定する言語コード
• file_format：音声ファイル形式（wav、mp3 など）
• task："transcribe" または "translate"（英語に翻訳します）

3. download_youtube

YouTube 動画をダウンロードします。

Parameters:

• url：YouTube 動画の URL
• keep_file：True の場合、ダウンロードしたファイルを保持します（デフォルト：True）

4. transcribe_youtube

YouTube 動画をダウンロードして文字起こしします。

Parameters:

• url：YouTube 動画の URL
• language：（任意）特定の言語を指定する言語コード
• task："transcribe" または "translate"（英語に翻訳します）
• keep_file：True の場合、ダウンロードしたファイルを保持します（デフォルト：True）

Example Prompts for Claude Desktop

• 「/Users/username/Desktop/recording.mp3 にある音声ファイルを文字起こしして」
• 「このスペイン語の音声録音を英語に翻訳して」（音声ファイルをアップロードする場合）
• 「この録音では何と言っていますか？」（音声ファイルをアップロードする場合）
• 「この YouTube 動画をダウンロードして文字起こしして：https://www.youtube.com/watch?v=dQw4w9WgXcQ」
• 「この YouTube 動画をダウンロードして：https://www.youtube.com/watch?v=dQw4w9WgXcQ」

動作の仕組み

このサーバーは MCP Python SDK を使用して、Claude などのクライアントに MLX Whisper の文字起こし機能を提供します。文字起こしがリクエストされると、次の処理が行われます。

1. 音声データを受信します（ファイルパス、Base64 エンコードされたデータ、または YouTube URL のいずれか）
2. YouTube URL の場合、動画を ~/.mlx-whisper-mcp/downloads にダウンロードします
3. Base64 データの場合、一時ファイルを作成します
4. MLX Whisper を使用して文字起こしを実行します
5. 文字起こしテキストを音声ファイルと同じ場所にある .txt ファイルに保存します
6. 文字起こしテキストをクライアントに返します
7. 一時ファイルを削除します（keep_file=True の場合を除く）

トラブルシューティング

• インポートエラー：MLX Whisper が見つからないというエラーが表示される場合は、Apple Silicon 搭載の Mac で実行していることを確認してください
• ファイルが見つからない：音声ファイルを指定する際は、絶対パスを使用してください
• メモリの問題：非常に長い音声ファイルでは、大規模モデルによってメモリに負荷がかかる場合があります
• YouTube のダウンロードエラー：動画によっては、視聴制限があったり認証が必要だったりする場合があります
• JSON エラー：ログに「not valid JSON」エラーが表示される場合は、サーバーのログ出力が stderr に正しく出力されるよう設定してください

ライセンス

Apache License 2.0 詳細は LICENSE を参照してください。