MCP Whisper Transcription Server

An MCP (Model Context Protocol) server for audio/video transcription using MLX-optimized Whisper models. Optimized for Apple Silicon devices with ultra-fast performance.

✨ Features

• 🚀 MLX-Optimized: Leverages Apple Silicon for blazing-fast transcription (up to 10x faster)

• 🎯 Multiple Formats: Supports txt, md, srt, and json output formats

• 🎬 Video Support: Automatically extracts audio from video files (MP4, MOV, AVI, MKV)

• 📦 Batch Processing: Process multiple files in parallel with configurable workers

• 🔧 MCP Integration: Full MCP protocol support with tools and resources

• 📊 Performance Tracking: Built-in performance monitoring and reporting

• 🎛️ Flexible Models: Choose from 6 different Whisper models (tiny to large-v3-turbo)

• 🛠️ Error Handling: Robust error handling and validation

• 📈 Concurrent Processing: Thread-safe concurrent transcription support

• 🔇 Voice Activity Detection: Optional VAD to remove silence and speed up processing

• 🧹 Hallucination Prevention: Advanced filtering to remove common transcription artifacts

Related MCP server: Fast-Whisper-MCP-Server

🏆 Performance

• Speed: Up to 10x realtime transcription on Apple Silicon

• Memory: Optimized memory usage (< 500MB for most files)

• Concurrent: Handle multiple transcriptions simultaneously

• Scalable: Batch process hundreds of files efficiently

🚀 Quick Start

Prerequisites

• Apple Silicon Mac (M1, M2, M3, or later)

• Python 3.10+

• FFmpeg (for video support)

Installation

1. Install FFmpeg (if not already installed):

   brew install ffmpeg

2. Clone the repository:

   git clone https://github.com/galacoder/mcp-whisper-transcription.git
   cd mcp-whisper-transcription

3. Install Poetry (if not already installed):

   curl -sSL https://install.python-poetry.org | python3 -

4. Install dependencies:

   poetry install

5. Test the installation:

   poetry run python src/whisper_mcp_server.py --help

📋 Configuration

Environment Variables

Create a .env file to customize settings:

# Model Configuration
DEFAULT_MODEL=mlx-community/whisper-large-v3-turbo
OUTPUT_FORMATS=txt,md,srt,json

# Performance Settings
MAX_WORKERS=4
TEMP_DIR=./temp

# Optional: API Keys for future cloud features
# OPENAI_API_KEY=your_key_here

Available Models

🔧 Usage

Claude Desktop Integration

Add to your Claude Desktop configuration file:

{
 "mcpServers": {
 "whisper-transcription": {
 "command": "poetry",
 "args": ["run", "python", "src/whisper_mcp_server.py"],
 "cwd": "/absolute/path/to/mcp-whisper-transcription"
 }
 }
}

📍 Configuration File Locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Standalone Usage

# Run the MCP server directly
poetry run python src/whisper_mcp_server.py

# Or use the development server
poetry run python -m src.whisper_mcp_server

🛠️ Available Tools & Resources

MCP Tools

MCP Resources

Quick Examples

# Single file transcription
result = await client.call_tool("transcribe_file", {
 "file_path": "interview.mp4",
 "output_formats": "txt,srt",
 "model": "mlx-community/whisper-large-v3-turbo"
})

# Transcription with Voice Activity Detection
result = await client.call_tool("transcribe_file", {
 "file_path": "long_interview.mp4",
 "output_formats": "txt,srt",
 "use_vad": True # Remove silence for faster processing
})

# Batch processing
result = await client.call_tool("batch_transcribe", {
 "directory": "./podcasts",
 "pattern": "*.mp3",
 "max_workers": 4
})

# Check supported formats
formats = await client.call_tool("get_supported_formats", {})

🧪 Development

Running Tests

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src --cov-report=html

# Run specific test file
poetry run pytest tests/test_mcp_tools.py -v

Code Quality

# Format code
poetry run black .
poetry run isort .

# Type checking (optional)
poetry run mypy src/

# Lint code
poetry run flake8 src/

Project Structure

mcp-whisper-transcription/
├── src/
│ └── whisper_mcp_server.py # Main MCP server
├── tests/ # Comprehensive test suite
├── examples/ # Usage examples and test files
├── transcribe_mlx.py # MLX Whisper integration
├── whisper_utils.py # Utility functions
└── pyproject.toml # Project configuration

📊 Performance Benchmarks

Test Results (Apple M3 Max)

🔧 Troubleshooting

Common Issues

1. FFmpeg not found

   brew install ffmpeg

2. Model download slow

   • Models are cached in ~/.cache/huggingface/

   • First download can be slow but subsequent runs are fast

3. Memory issues

   • Use smaller models (tiny/base) for large files

   • Reduce MAX_WORKERS for concurrent processing

4. Permission errors

   • Ensure proper file permissions

   • Check output directory write access

See TROUBLESHOOTING.md for detailed solutions.

📋 Requirements

• Python 3.10+

• Apple Silicon Mac (M1, M2, M3, or later)

• FFmpeg (for video file support)

• 4GB+ RAM (8GB+ recommended for large models)

• 2GB+ free disk space (for model cache)

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

🙏 Acknowledgments

• Built with FastMCP - Modern MCP server framework

• Powered by MLX Whisper - Apple Silicon optimization

• Original Whisper by OpenAI - Revolutionary speech recognition

• Thanks to the MLX team at Apple for the incredible performance optimizations

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers