Video Transcriber MCP Server

A Model Context Protocol (MCP) server that transcribes videos from 1000+ platforms using whisper.cpp — 4-10x faster than Python Whisper. Built with TypeScript for type safety and available via npx for easy installation.

🦀 Prefer a standalone binary? Check out the Rust version, which embeds whisper.cpp directly (no external CLI needed) and adds an optional HTTP/REST API. Available on crates.io with cargo install video-transcriber-mcp.

✨ What's New

v2.0.0

• ⚡ whisper.cpp engine: switched from Python openai-whisper to whisper.cpp (via the whisper-cli binary) for 4-10x faster transcription with lower memory usage. ⚠️ Breaking: install whisper-cpp and download models (see Prerequisites).
• 🛰️ Remote whisper worker: offload transcription to a GPU service with REMOTE_WHISPER_URL.
• 🍪 yt-dlp cookies: authenticate for age-restricted / members-only videos and bypass YouTube's bot check via YT_DLP_COOKIES or YT_DLP_COOKIES_FROM_BROWSER.
• 🧹 Transcript management tools: get_latest_transcript, delete_transcript, cleanup_old_transcripts, delete_all_transcripts.
• 📚 Smarter listing: list_transcripts now sorts newest-first and supports a limit.

Earlier

• 🌍 Multi-Platform Support: 1000+ video platforms (YouTube, Vimeo, TikTok, Twitter/X, Facebook, Instagram, Twitch, educational sites, and more) via yt-dlp
• 💻 Cross-Platform: Works on macOS, Linux, and Windows
• 🎛️ Configurable Whisper Models: Choose from tiny, base, small, medium, or large models
• 🌐 Language Support: Transcribe in 90+ languages or use auto-detection
• 🔄 Automatic Retries: Network failures are handled automatically with exponential backoff
• 🎯 Platform Detection: Automatically detects the video platform

⚠️ Legal Notice

This tool is intended for educational, accessibility, and research purposes only.

Before using this tool, please understand:

• Most platforms' Terms of Service generally prohibit downloading content
• You are responsible for ensuring your use complies with applicable laws
• This tool should primarily be used for:
  • ✅ Your own content
  • ✅ Creating accessibility features (captions for deaf/hard of hearing)
  • ✅ Educational and research purposes (where permitted)
  • ✅ Content you have explicit permission to download

Please read LEGAL.md for detailed legal information before using this tool.

We do not encourage or endorse violation of any platform's Terms of Service or copyright infringement. Use responsibly and ethically.

Features

• 🎥 Download audio from 1000+ video platforms (powered by yt-dlp)
• 📂 Transcribe local video files (mp4, avi, mov, mkv, and more)
• ⚡ Transcribe using whisper.cpp locally (no API key needed) — 4-10x faster than Python Whisper
• 🛰️ Optional remote whisper worker for GPU offload (REMOTE_WHISPER_URL)
• 🍪 yt-dlp cookie support for age-restricted / bot-checked videos
• 🎛️ Configurable Whisper models (tiny, base, small, medium, large)
• 🌐 Support for 90+ languages with auto-detection
• 📝 Generate transcripts in multiple formats (TXT, JSON, Markdown)
• 📚 List, read, and manage previous transcripts (list/latest/delete/cleanup)
• 🔌 Integrate seamlessly with Claude Code or any MCP client
• 🔒 Full type safety with TypeScript
• 🔍 Automatic dependency checking
• 🔄 Automatic retry logic for network failures
• 🎯 Platform detection (shows which platform you're transcribing from)

Supported Platforms

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

• Social Media: YouTube, TikTok, Twitter/X, Facebook, Instagram, Reddit, LinkedIn
• Video Hosting: Vimeo, Dailymotion, Twitch
• Educational: Coursera, Udemy, Khan Academy, LinkedIn Learning, edX
• News: BBC, CNN, NBC, PBS
• Conference/Tech: YouTube (tech talks), Vimeo (conferences)
• And many, many more!

Run the list_supported_sites tool to see the complete list of 1000+ supported platforms.

Prerequisites

You need these tools installed: yt-dlp (video downloader), whisper.cpp (the whisper-cli binary), ffmpeg (audio processing), and — for YouTube — a JavaScript runtime (Deno). You also need to download at least one whisper.cpp model (see Whisper Models).

⚠️ YouTube needs Deno ≥ 2.3.0. Modern yt-dlp must run JavaScript to solve YouTube's signature / "n" challenges. Without a JS runtime, YouTube downloads fail with errors that look like bot-detection (No supported JavaScript runtime could be found, Signature solving failed, n challenge solving failed, HTTP 403). yt-dlp auto-detects Deno — but it must be version 2.3.0 or newer; an older Deno is detected yet still can't solve the challenge. Run deno --version to check and deno upgrade if needed. Non-YouTube sites generally don't need it. This is a yt-dlp requirement, not specific to this tool. (The official yt-dlp binaries bundle the challenge-solver scripts, so Deno is all you add.)

If you set REMOTE_WHISPER_URL to offload transcription to a remote worker, you can skip installing whisper-cpp and downloading models locally.

macOS

brew install yt-dlp       # Video downloader (supports 1000+ sites)
brew install whisper-cpp  # whisper.cpp transcription (installs `whisper-cli`)
brew install ffmpeg       # Audio processing
brew install deno         # JavaScript runtime (required for YouTube)

Linux

# Ubuntu/Debian
sudo apt update
sudo apt install ffmpeg
pip install yt-dlp
curl -fsSL https://deno.land/install.sh | sh   # JavaScript runtime (required for YouTube)
# whisper.cpp: build from source, then put `whisper-cli` on your PATH
git clone https://github.com/ggerganov/whisper.cpp && cd whisper.cpp && make
# copy build/bin/whisper-cli to /usr/local/bin, or set WHISPER_CPP_BINARY to its path

Windows

# Install Python from python.org first
pip install yt-dlp

# Install ffmpeg + deno using Chocolatey
choco install ffmpeg
choco install deno   # JavaScript runtime (required for YouTube)

# whisper.cpp: download a prebuilt release from
# https://github.com/ggerganov/whisper.cpp/releases and put whisper-cli.exe on PATH,
# or set WHISPER_CPP_BINARY to its full path.

Deno not on PATH? If you installed Deno but yt-dlp still reports "No supported JavaScript runtime" (common when the installer drops it in ~/.deno/bin), symlink it somewhere already on PATH — e.g. ln -sf ~/.deno/bin/deno ~/.local/bin/deno — or add ~/.deno/bin to your PATH.

Verify installations (all platforms)

yt-dlp --version
whisper-cli --help
ffmpeg -version
deno --version

Whisper Models

whisper.cpp uses ggml model files stored in ~/.cache/video-transcriber-mcp/models/. Download them with the bundled script:

# Download a single model (recommended: start with base)
bash scripts/download-models.sh base

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

Windows: download-models.sh is a Bash script — run it from Git Bash or WSL. Or download the model manually: grab ggml-base.bin (or another size) from https://huggingface.co/ggerganov/whisper.cpp/tree/main and drop it into %USERPROFILE%\.cache\video-transcriber-mcp\models\.

| Model | Size | Notes | |--------|---------|-------------------------------| | tiny | ~75 MB | fastest, lowest accuracy | | base | ~142 MB | recommended default | | small | ~466 MB | good balance | | medium | ~1.5 GB | high accuracy | | large | ~2.9 GB | best accuracy, slowest |

Run the check_dependencies tool at any time to see which models are installed.

Quick Start

For End Users (Using npx)

Add to your Claude Code config (~/.claude/settings.json):

{
  "mcpServers": {
    "video-transcriber": {
      "command": "npx",
      "args": ["-y", "video-transcriber-mcp"]
    }
  }
}

Or use directly from GitHub:

{
  "mcpServers": {
    "video-transcriber": {
      "command": "npx",
      "args": [
        "-y",
        "github:nhatvu148/video-transcriber-mcp"
      ]
    }
  }
}

That's it! No installation needed. npx will automatically download and run the package.

For Local Development

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

# Install dependencies
npm install
# or
bun install

# Build the project
npm run build

# Use in Claude Code with local path
{
  "mcpServers": {
    "video-transcriber": {
      "command": "npx",
      "args": ["-y", "/path/to/video-transcriber-mcp"]
    }
  }
}

Usage

From Claude Code

Once configured, you can use these tools in Claude Code:

Transcribe a video from any platform

Please transcribe this YouTube video: https://www.youtube.com/watch?v=VIDEO_ID

Transcribe this TikTok video: https://www.tiktok.com/@user/video/123456789

Get the transcript from this Vimeo video with high accuracy: https://vimeo.com/123456789
(use model: large)

Transcribe this Spanish tutorial video: https://youtube.com/watch?v=VIDEO_ID
(language: es)

Transcribe a local video file

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

Transcribe ~/Downloads/lecture.mov with high accuracy
(use model: medium)

Claude will use the transcribe_video tool automatically with optional parameters for model and language.

List all supported platforms

What platforms can you transcribe videos from?

List available transcripts

List all my video transcripts

Check dependencies

Check if my video transcriber dependencies are installed

Read a transcript

Show me the transcript for [video name]

Programmatic Usage

If you install the package:

npm install video-transcriber-mcp

You can import and use it programmatically:

import { transcribeVideo, checkDependencies, WhisperModel } from 'video-transcriber-mcp';

// Check dependencies — returns a human-readable status string
console.log(checkDependencies());

// Transcribe a video from URL with custom options
const result = await transcribeVideo({
  url: 'https://www.youtube.com/watch?v=VIDEO_ID',
  outputDir: '/path/to/output',
  model: 'medium', // tiny, base, small, medium, large
  language: 'en', // or 'auto' for auto-detection
  onProgress: (progress) => console.log(progress)
});

// Or transcribe a local video file
const localResult = await transcribeVideo({
  url: '/path/to/video.mp4',  // Local file path instead of URL
  outputDir: '/path/to/output',
  model: 'base',
  language: 'auto',
  onProgress: (progress) => console.log(progress)
});

console.log('Title:', result.metadata.title);
console.log('Platform:', result.metadata.platform);
console.log('Words:', result.wordCount);
console.log('Model:', result.modelUsed);
console.log('Files:', result.files);

Output

Transcripts are saved to ~/Downloads/video-transcripts/ by default.

For each video, three files are generated:

1. .txt - Plain text transcript
2. .json - JSON with video metadata, the transcript, and the model used
3. .md - Markdown with video metadata and formatted transcript

Example

~/Downloads/video-transcripts/
├── 7JBuA1GHAjQ-From-AI-skeptic-to-UNFAIR-advantage.txt
├── 7JBuA1GHAjQ-From-AI-skeptic-to-UNFAIR-advantage.json
└── 7JBuA1GHAjQ-From-AI-skeptic-to-UNFAIR-advantage.md

MCP Tools

transcribe_video

Transcribe videos from 1000+ platforms or local video files to text.

Parameters:

• url (required): Video URL from any supported platform OR path to a local video file (mp4, avi, mov, mkv, etc.)
• output_dir (optional): Output directory path
• model (optional): Whisper model - "tiny", "base" (default), "small", "medium", "large"
• language (optional): Language code (ISO 639-1: "en", "es", "fr", etc.) or "auto" (default)

Model Comparison: | Model | Speed | Accuracy | Use Case | |-------|-------|----------|----------| | tiny | ⚡⚡⚡⚡⚡ | ⭐⭐ | Quick drafts, testing | | base | ⚡⚡⚡⚡ | ⭐⭐⭐ | General use (default) | | small | ⚡⚡⚡ | ⭐⭐⭐⭐ | Better accuracy | | medium | ⚡⚡ | ⭐⭐⭐⭐⭐ | High accuracy | | large | ⚡ | ⭐⭐⭐⭐⭐⭐ | Best accuracy, slow |

list_transcripts

List all available transcripts with metadata, sorted by modification time (newest first).

Parameters:

• output_dir (optional): Directory to list
• limit (optional): Return only the N most recent transcripts

get_latest_transcript

Get the path and details of the most recently created/modified transcript. Useful to avoid accidentally reading an old transcript.

Parameters:

• output_dir (optional): Directory to search

delete_transcript

Delete a specific transcript by video ID (removes all associated .txt, .json, .md files).

Parameters:

• video_id (required): The video ID to delete (e.g. dQw4w9WgXcQ)
• output_dir (optional): Directory to delete from

cleanup_old_transcripts

Delete transcripts older than a given number of days.

Parameters:

• days (required): Delete files older than this many days
• output_dir (optional): Directory to clean

delete_all_transcripts

Delete ALL transcripts in the output directory. Cannot be undone.

Parameters:

• confirm (required): Must be true to actually delete
• output_dir (optional): Directory to clear

check_dependencies

Verify that all required dependencies (yt-dlp, ffmpeg, whisper.cpp) and models are installed.

list_supported_sites

List all 1000+ supported video platforms.

Environment Variables

All are optional. See .env.example for details. When using the MCP server, set these in your client's env block.

| Variable | Description | |----------|-------------| | YT_DLP_COOKIES | Path to a Netscape-format cookies file (--cookies). Preferred on headless/Linux. | | YT_DLP_COOKIES_FROM_BROWSER | Browser to read cookies from (chrome, brave, edge, firefox, safari, …). Ignored if YT_DLP_COOKIES is set. | | REMOTE_WHISPER_URL | Offload transcription to a remote HTTP worker instead of running whisper.cpp locally. | | WHISPER_CPP_BINARY | Override the whisper.cpp CLI name/path (default whisper-cli). |

Example Claude Code config with cookies:

{
  "mcpServers": {
    "video-transcriber": {
      "command": "npx",
      "args": ["-y", "video-transcriber-mcp"],
      "env": {
        "YT_DLP_COOKIES_FROM_BROWSER": "chrome"
      }
    }
  }
}

Configuration Examples

Claude Code (Recommended)

{
  "mcpServers": {
    "video-transcriber": {
      "command": "npx",
      "args": ["-y", "video-transcriber-mcp"]
    }
  }
}

From GitHub (Latest)

{
  "mcpServers": {
    "video-transcriber": {
      "command": "npx",
      "args": ["-y", "github:nhatvu148/video-transcriber-mcp"]
    }
  }
}

Local Development

{
  "mcpServers": {
    "video-transcriber": {
      "command": "npx",
      "args": ["-y", "/absolute/path/to/video-transcriber-mcp"]
    }
  }
}

Development

Setup

# Install dependencies
npm install

# Build the project
npm run build

# Type check
npm run check

# Development mode (requires Bun)
bun run dev

# Clean build artifacts
npm run clean

Project Structure

video-transcriber-mcp/
├── src/
│   ├── index.ts          # MCP server implementation (8 tools)
│   └── transcriber.ts    # Core transcription logic (whisper.cpp)
├── scripts/
│   └── download-models.sh # Download whisper.cpp ggml models
├── dist/                 # Built JavaScript (generated)
├── package.json          # Package configuration
├── tsconfig.json         # TypeScript configuration
├── .env.example          # Documented environment variables
├── LICENSE               # MIT License
└── README.md             # This file

Scripts

| Command | Description | |---------|-------------| | npm run build | Compile TypeScript to JavaScript | | npm run dev | Development mode with hot reload (Bun) | | npm run check | TypeScript type checking | | npm run clean | Remove dist/ directory | | npm run prepublishOnly | Pre-publish build (automatic) |

Publishing

# Build the project
npm run build

# Test locally first
npx . --help

# Publish to npm (bump version first)
npm version patch  # or minor, major
npm publish

# Or publish from GitHub
# Push to GitHub and users can use:
# npx github:username/video-transcriber-mcp

Troubleshooting

Dependencies not installed

See the Prerequisites section above for platform-specific installation instructions.

npx can't find the package

Make sure the package is:

• Published to npm, OR
• Available on GitHub with proper package.json

TypeScript errors

npm run check

Permission denied

The build process automatically makes dist/index.js executable via the fix-shebang script.

"Unsupported URL" error

The platform might not be supported by yt-dlp. Run list_supported_sites to see all supported platforms.

"Whisper model not found"

Download the model you're requesting: bash scripts/download-models.sh base (or all). Models live in ~/.cache/video-transcriber-mcp/models/. Run check_dependencies to see what's installed.

"whisper.cpp CLI ('whisper-cli') not found"

Install whisper.cpp (brew install whisper-cpp on macOS) or set WHISPER_CPP_BINARY to the full path of your whisper-cli (or legacy main) binary.

YouTube fails: "No supported JavaScript runtime" / "Signature solving failed" / HTTP 403

yt-dlp needs a JavaScript runtime to download from YouTube. Install Deno ≥ 2.3.0 (brew install deno, choco install deno, or curl -fsSL https://deno.land/install.sh | sh) — yt-dlp auto-detects it. Two common gotchas:

• Deno not found even though it's installed → it landed in ~/.deno/bin, which isn't on PATH. Symlink it: ln -sf ~/.deno/bin/deno ~/.local/bin/deno.
• n challenge solving failed persists with Deno installed → your Deno is older than 2.3.0. Run deno --version, then deno upgrade. (This is the sneaky one — an old Deno is detected but silently can't solve the challenge.)

Verify with deno --version. See Prerequisites.

These errors often masquerade as bot-detection, but the fix is a JS runtime, not cookies. Also keep yt-dlp current (yt-dlp -U or brew upgrade yt-dlp) — an outdated yt-dlp makes YouTube failures worse.

YouTube "Sign in to confirm you're not a bot"

First confirm you have Deno installed (see above) and yt-dlp is up to date — that resolves most cases. For genuinely gated content (age-restricted / members-only), set YT_DLP_COOKIES (path to a cookies file) or YT_DLP_COOKIES_FROM_BROWSER (e.g. chrome). See Environment Variables.

Performance

whisper.cpp is roughly 4-10x faster than Python openai-whisper on the same hardware, using less memory. Actual processing time depends on your CPU (P-core count on Apple Silicon), the selected model, and the video length.

Tip: start with the base model and move up to medium/large only when you need more accuracy.

Advanced Configuration

Custom Whisper Model

Specify in the tool call parameters:

{
  "url": "https://youtube.com/watch?v=...",
  "model": "large"
}

Custom Language

Specify the language code:

{
  "url": "https://youtube.com/watch?v=...",
  "language": "es"
}

Custom Output Directory

Specify in the tool call:

{
  "url": "https://youtube.com/watch?v=...",
  "output_dir": "/custom/path"
}

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details

TypeScript vs Rust Version

Project scope: The Rust version is the source of truth. This TypeScript package is intentionally kept small and stable — a lean local stdio MCP server for the npm/npx audience. Advanced/SaaS features (HTTP transport, auth, credits/billing, LLM summaries) live only in the Rust version and are not ported here. New capabilities land in Rust first; this package only tracks the shared MCP tool contract.

Both versions use whisper.cpp for transcription and expose the same MCP tools.

Pick the TypeScript version (this one) for:

• ✅ Quick setup with npx (no compilation)
• ✅ Node.js ecosystem familiarity
• ℹ️ Calls the whisper-cli binary (install whisper-cpp separately)

Pick the Rust version for:

• 📦 Standalone binary — whisper.cpp is embedded, no external CLI to install
• 💾 Lower memory usage and native startup
• 🌐 HTTP/REST API transport, auth, credits, and other SaaS features

Both support the same MCP protocol and work identically with Claude Code!

Links

• GitHub Repository
• npm Package
• 🦀 Rust Version ← For better performance
• Issues
• Model Context Protocol

Acknowledgments

• whisper.cpp for fast local transcription
• OpenAI Whisper for the underlying models
• yt-dlp for multi-platform video downloading (1000+ sites)
• Model Context Protocol SDK
• Claude by Anthropic

Made with ❤️ for the MCP community