Mlx Whisper MCP

🚀 MLX Whisper MCP Server

A simple Model Context Protocol (MCP) server that provides audio transcription capabilities on Apple Silicon Macs using MLX Whisper.

✨ Features

• Transcribe audio files directly from disk.
• Transcribe audio from base64-encoded data.
• Download and transcribe YouTube videos.
• Utilize the high-quality mlx-community/whisper-large-v3-turbo model.
• Automatically manage dependencies via the uv run script.
• Offer rich console output for easy debugging.
• Save transcribed text files alongside audio files.

📦 Prerequisites

• Python 3.12 or higher.
• Apple Silicon Mac (M series).
• uv installed (pip install uv or curl -sS https://astral.sh/uv/install.sh | bash).

🚀 Quick Start

Run directly using uv run:

uv run mlx_whisper_mcp.py

That's it! The script will automatically install its dependencies and start the MCP server.

💻 Integration with Claude Desktop

1. Edit your Claude Desktop configuration file:

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

# On Windows:
code %APPDATA%\Claude\claude_desktop_config.json

2. Add the MLX Whisper MCP server configuration:

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

3. Restart Claude Desktop.

🛠️ Available Tools

The server provides the following tools:

1. transcribe_file

Transcribe an audio file from a path on disk. Parameters:

• file_path: Path to the audio file.
• language: (Optional) Language code to force a specific language.
• task: "transcribe" or "translate" (translate to English).

2. transcribe_audio

Transcribe audio from base64-encoded data. Parameters:

• audio_data: Base64-encoded audio data.
• language: (Optional) Language code to force a specific language.
• file_format: Audio file format (e.g., wav, mp3).
• task: "transcribe" or "translate" (translate to English).

3. download_youtube

Download a YouTube video. Parameters:

• url: YouTube video URL.
• keep_file: If true, keep the downloaded file (default: true).

4. transcribe_youtube

Download and transcribe a YouTube video. Parameters:

• url: YouTube video URL.
• language: (Optional) Language code to force a specific language.
• task: "transcribe" or "translate" (translate to English).
• keep_file: If true, keep the downloaded file (default: true).

💡 Example Prompt

How to use this server when integrating with Claude Desktop?

🔧 How It Works

1. The user sends a request to the server, specifying the task and relevant parameters.
2. The server performs the corresponding operation based on the task type, such as transcribing audio or downloading a video.
3. After processing, the server returns the result to the user.

🐞 Troubleshooting

• Problem: Unable to start the server
  • Check if the correct Python version and the uv tool are installed.
  • Ensure the script path is correct.
• Problem: Transcription fails
  • Check the format and path of the input file.
  • Ensure a stable network connection (for YouTube downloads).
• Problem: Configuration does not take effect
  • Verify that the JSON file has correct syntax without errors.
  • Ensure the server has been restarted correctly to apply the changes.

📄 License

This project is licensed under the [LICENSE] agreement. Refer to the project documentation for detailed licensing information.