video-transcriber-mcp-rs

# Video Transcriber MCP 🚀

**High-performance video transcription MCP server using whisper.cpp (Rust)**

[![License: MIT OR Apache-2.0](https://img.shields.io/crates/l/video-transcriber-mcp.svg)](#license)
[![Rust](https://img.shields.io/badge/rust-1.85%2B-orange.svg)](https://www.rust-lang.org/)
[![crates.io](https://img.shields.io/crates/v/video-transcriber-mcp.svg)](https://crates.io/crates/video-transcriber-mcp)

A Model Context Protocol (MCP) server that transcribes videos from **1000+ platforms** using whisper.cpp. Built with Rust for maximum performance and efficiency.

## 📦 Installation

### Homebrew (macOS/Linux) - Recommended

The easiest way to install with all dependencies:

```bash
brew install nhatvu148/tap/video-transcriber-mcp
```

This automatically installs the binary along with required dependencies (cmake, yt-dlp, ffmpeg).

### Cargo Install

If you have Rust installed:

```bash
cargo install video-transcriber-mcp
```

**Note:** You'll need to manually install dependencies: `yt-dlp`, `ffmpeg`, `cmake`

### Pre-built Binaries

Download from [GitHub Releases](https://github.com/nhatvu148/video-transcriber-mcp-rs/releases/latest):

```bash
# macOS (Intel)
curl -L https://github.com/nhatvu148/video-transcriber-mcp-rs/releases/latest/download/video-transcriber-mcp-x86_64-apple-darwin.tar.gz | tar xz
sudo mv video-transcriber-mcp /usr/local/bin/

# macOS (Apple Silicon)
curl -L https://github.com/nhatvu148/video-transcriber-mcp-rs/releases/latest/download/video-transcriber-mcp-aarch64-apple-darwin.tar.gz | tar xz
sudo mv video-transcriber-mcp /usr/local/bin/

# Linux (x86_64) — no ARM64 Linux build, see issue #13; use `cargo install`
curl -L https://github.com/nhatvu148/video-transcriber-mcp-rs/releases/latest/download/video-transcriber-mcp-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv video-transcriber-mcp /usr/local/bin/

# Windows: Download .zip from releases page
```

**Note:** You'll need to manually install dependencies: `yt-dlp`, `ffmpeg`

### Claude Code plugin

Installs the MCP server and a `/transcribe` skill in one step:

```bash
/plugin marketplace add nhatvu148/video-transcriber-mcp-rs
/plugin install video-transcriber@nhatvu148-tools
```

The plugin registers the MCP server for you, but it does **not** install the binary — run one of the install commands above first, so `video-transcriber-mcp` is on your `PATH`.

## 🎯 Why Rust?

This version uses **whisper.cpp** (C++ implementation with Rust bindings) instead of Python's OpenAI Whisper:

| Advantage | whisper.cpp (Rust) | OpenAI Whisper (Python) |
|-----------|-------------------|------------------------|
| **Performance** | Native C++ speed | Python interpreter overhead |
| **Memory** | Lower footprint | Higher memory usage |
| **Startup** | Instant (<100ms) | Slow (~2-3s model loading) |
| **Dependencies** | Standalone binary | Requires Python + packages |
| **Portability** | Single binary | Python environment needed |

Real-world performance depends on your hardware, video length, and chosen model.

## ✨ Features

- 🚀 **High performance** transcription using whisper.cpp (C++ with Rust bindings)
- 🎥 Download from **1000+ platforms** (YouTube, Vimeo, TikTok, Twitter, etc.)
- 📂 Transcribe **local video files** (mp4, avi, mov, mkv, etc.)
- 🎤 **100% offline** transcription (privacy-first)
- 🎛️ **5 model sizes** (tiny, base, small, medium, large)
- 🌐 **90+ languages** supported
- 📝 **Multiple output formats** (TXT, JSON, Markdown)
- 🔌 **MCP integration** for Claude Code
- 🌐 **Dual transport** - stdio (local) and Streamable HTTP (remote)
- ⚡ **Native binary** - no Python or Node.js required
- 💾 **Low memory footprint** compared to Python implementations

## ⚡ Quick Start (Using Taskfile)

**The fastest way to get started:**

```bash
# 1. Install Task (if not already installed)
brew install go-task/tap/go-task

# 2. Complete setup (build + download model)
task setup

# 3. Run a quick test
task test:quick

# Done! 🎉
```

**Available Commands:**
```bash
task setup           # Complete project setup
task test:quick      # Test with short video
task benchmark       # Run performance benchmark
task deps:check      # Check dependencies
task download:base   # Download base model
task help            # Show all commands
```

See [Taskfile.yml](Taskfile.yml) for all available tasks.

---

## 🌐 Transport Modes

The server supports two transport modes:

### Stdio Transport (Default)

Standard I/O transport for local CLI usage with Claude Code. This is the default mode.

```bash
video-transcriber-mcp
# or explicitly:
video-transcriber-mcp --transport stdio
```

### Streamable HTTP Transport

HTTP transport for remote access. Allows the MCP server to be accessed over the network.

```bash
# Start HTTP server on default port (8080)
video-transcriber-mcp --transport http

# Custom host and port
video-transcriber-mcp --transport http --host 0.0.0.0 --port 3000
```

**Remote MCP Client Configuration:**

For HTTP transport, configure your MCP client with the URL:

```json
{
  "mcpServers": {
    "video-transcriber-mcp": {
      "url": "http://localhost:8080/mcp"
    }
  }
}
```

**Benefits of HTTP Transport:**
- No local installation required for clients
- Centralized server deployment
- Automatic updates (server-side)
- Better for team environments
- Compatible with serverless platforms

### CLI Options

```bash
video-transcriber-mcp --help

Options:
  -t, --transport <TRANSPORT>  Transport mode [default: stdio] [possible values: stdio, http]
      --host <HOST>            Host address for HTTP transport [default: 127.0.0.1]
  -p, --port <PORT>            Port for HTTP transport [default: 8080]
  -h, --help                   Print help
  -V, --version                Print version
```

---

## 📦 Manual Build from Source

### Prerequisites

1. **Rust** (1.85+ for Rust 2024 edition)
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

2. **yt-dlp** (for downloading videos)
```bash
# macOS
brew install yt-dlp

# Linux
pip install yt-dlp

# Windows
winget install yt-dlp.yt-dlp
```

3. **FFmpeg** (for audio processing)
```bash
# macOS
brew install ffmpeg

# Linux
sudo apt install ffmpeg  # Debian/Ubuntu
sudo dnf install ffmpeg  # Fedora

# Windows
choco install ffmpeg
```

### Build from Source

```bash
# Clone the repository
git clone https://github.com/nhatvu148/video-transcriber-mcp-rs.git
cd video-transcriber-mcp-rs

# Build the project
cargo build --release

# The binary will be at: target/release/video-transcriber-mcp-rs
```

### Download Whisper Models

```bash
# Download base model (recommended for testing)
bash scripts/download-models.sh base

# Or download all models
bash scripts/download-models.sh all
```

Models are stored in `~/.cache/video-transcriber-mcp/models/`

## 🚀 Quick Start

### MCP Server (for Claude Code)

Add to `~/.claude/settings.json`:

**Option 1: If installed via GitHub Release or cargo install:**
```json
{
  "mcpServers": {
    "video-transcriber-mcp": {
      "command": "video-transcriber-mcp",
      "args": [],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}
```

**Option 2: If built from source:**
```json
{
  "mcpServers": {
    "video-transcriber-mcp": {
      "command": "/absolute/path/to/video-transcriber-mcp-rs/target/release/video-transcriber-mcp",
      "args": [],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}
```

Then use in Claude Code:

**Basic transcription (uses base model by default):**
```
Please transcribe this YouTube video: https://www.youtube.com/watch?v=VIDEO_ID
```

**Transcribe with specific model:**
```
Transcribe this video using the large model for best accuracy:
https://www.youtube.com/watch?v=VIDEO_ID
```

**Transcribe local video file:**
```
Transcribe this local video file: /Users/myname/Videos/meeting.mp4
```

**Transcribe in specific language:**
```
Transcribe this Spanish video: https://www.youtube.com/watch?v=VIDEO_ID
(language: es, model: medium)
```

## 📊 Performance

### Expected Performance Characteristics

Based on whisper.cpp vs OpenAI Whisper benchmarks from the community:

**Transcription Speed** (approximate, varies by hardware):
- whisper.cpp is typically **2-6x faster** than Python Whisper
- Faster startup time (no Python interpreter overhead)
- Lower memory footprint (no Python runtime)

**Real-world factors that affect performance:**
- CPU: More cores = faster processing
- Model size: Tiny is fastest, Large is slowest but most accurate
- Video length: Longer videos take proportionally more time
- Audio complexity: Clear speech transcribes faster than noisy audio

### Want to help?

We're collecting real benchmark data! If you run both versions, please share your results:
- Hardware specs (CPU, RAM)
- Video length tested
- Model used
- Time taken for each version

Open an issue with your benchmark results to help improve this section!

## 🎛️ Model Comparison

| Model | Speed | Accuracy | Memory | Use Case |
|-------|-------|----------|--------|----------|
| **tiny** | ⚡⚡⚡⚡⚡ | ⭐⭐ | ~400 MB | Quick drafts, testing |
| **base** | ⚡⚡⚡⚡ | ⭐⭐⭐ | ~600 MB | General use (default) |
| **small** | ⚡⚡⚡ | ⭐⭐⭐⭐ | ~1.2 GB | Better accuracy |
| **medium** | ⚡⚡ | ⭐⭐⭐⭐⭐ | ~2.5 GB | High accuracy |
| **large** | ⚡ | ⭐⭐⭐⭐⭐⭐ | ~4.8 GB | Best accuracy, slowest |

## 🌍 Supported Platforms

Thanks to yt-dlp, this tool supports **1000+ video platforms** including:

- **Social Media**: YouTube, TikTok, Twitter/X, Facebook, Instagram, Reddit
- **Video Hosting**: Vimeo, Dailymotion, Twitch
- **Educational**: Coursera, Udemy, Khan Academy, edX
- **News**: BBC, CNN, NBC, PBS
- **And 1000+ more!**

## 📝 Output Format

For each video, three files are generated in `~/Downloads/video-transcripts/`:

```
video-id-title.txt   # Plain text transcript
video-id-title.json  # JSON with metadata and timestamps
video-id-title.md    # Markdown with video info
```

### Example Output

```markdown
# How to Build Fast Software

**Video:** https://www.y