transcript MCP server
Commit Nov 11, 2026An MCP server that retrieves video transcripts, downloads videos, and generates subtitles using OpenAI Whisper or local speech-to-text.
Also known as JamesANZ/transcript-mcp
- Stars
- 0
- Tools
- 11
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 11, 2026
- License
- MIT
What is transcript MCP?
transcript is an MCP server that retrieves video transcripts, downloads videos, and generates subtitles using OpenAI Whisper or local speech-to-text. It exposes 11 tools, such as get-transcript, list-transcript-languages, download-video.
Summary generated from the project's README
About transcript MCP server
Extracting text from videos and managing media files is what developers can do using this tool. It provides a suite of capabilities for retrieving existing transcripts, downloading videos from platforms like YouTube, Bilibili, and Vimeo, and generating new subtitles. The server works with any platform supported by yt-dlp and requires local installations of yt-dlp and ffmpeg to function.
Users can choose between using the OpenAI Whisper API for high-accuracy transcription or running a local Whisper engine to avoid API costs. For audio processing, the server supports various input methods including URLs, base64 data, and file paths. It handles large audio files through a chunked upload system using transcribe_upload_start, transcribe_upload_append, and transcribe_upload_finalize. This setup is ideal for developers building AI workflows that require deep content understanding from video and audio assets.
What you can do with it
- 1Extract video transcriptsRetrieve existing captions from a YouTube or Vimeo video to summarize the content.
- 2Generate new subtitlesCreate srt or vtt subtitle files for a local video using AI speech-to-text.
- 3Download media for local useSave videos from various social platforms to a specific local directory in different qualities.
- 4Transcribe large audio filesProcess long audio recordings by uploading them in small base64 chunks.
Written from the project's README. Every use case is checked against a quote from it.
transcript MCP tools 11
Detected from the READMEget-transcriptlist-transcript-languagesdownload-videolist-downloadsgenerate-subtitlestranscribe-audiotranscribe_upload_starttranscribe_upload_appendtranscribe_upload_finalizetranscribe_get_jobtranscribe_cancel_job
| get-transcript | — | |
| list-transcript-languages | — | |
| download-video | — | |
| list-downloads | — | |
| generate-subtitles | — | |
| transcribe-audio | — | |
| transcribe_upload_start | — | |
| transcribe_upload_append | — | |
| transcribe_upload_finalize | — | |
| transcribe_get_job | — | |
| transcribe_cancel_job | — |
Configuration
OPENAI_API_KEYTRANSCRIPT_MCP_STORAGE_DIR
| Name | Description | |
|---|---|---|
| OPENAI_API_KEY | — | |
| TRANSCRIPT_MCP_STORAGE_DIR | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablejamesanz/transcript-mcp is public and reachablegithub.com/jamesanz/transcript-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/jamesanz/transcript-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model11 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubtranscript-mcp
A Model Context Protocol (MCP) server that provides comprehensive video tools: transcript retrieval, video downloading, automatic subtitle generation, and direct audio transcription. Works with YouTube, Bilibili, Vimeo, and any platform supported by yt-dlp.
Features
- Multi-Platform Support: Works with YouTube, Bilibili, Vimeo, and any platform supported by yt-dlp
- Video Transcripts: Extract existing transcripts/captions from videos
- Video Downloads: Download videos to local storage in various formats and qualities
- Auto Subtitle Generation: Generate subtitles using OpenAI Whisper API or local Whisper
- Client Audio Transcription:
audio_urlfetch (allowlisted), smallaudio_base64, chunked uploads, optional async jobs, server-side Opus compression, structured JSON results - Multiple URL Formats: Support for various URL formats from different platforms
- Timestamp Support: Include or exclude timestamps in transcript output
- Language Selection: Request transcripts or generate subtitles in specific languages
Tools
| Tool | Description |
|---|---|
get-transcript |
Retrieve existing transcripts from video platforms |
list-transcript-languages |
List available transcript languages for a video |
download-video |
Download videos to local storage |
list-downloads |
List downloaded video files |
generate-subtitles |
Generate subtitles using AI speech-to-text |
transcribe-audio |
Transcribe client-provided audio (URL / base64 / path / resource URI) |
transcribe_upload_start |
Start chunked upload for large audio payloads |
transcribe_upload_append |
Append one base64 chunk to an upload session |
transcribe_upload_finalize |
Finish upload and run transcription |
transcribe_get_job |
Poll async transcription jobs |
transcribe_cancel_job |
Cancel an async transcription job |
Prerequisites
- Node.js >= 16.0.0
- yt-dlp - Required for transcript fetching and video downloads
- ffmpeg - Required for subtitle generation, audio normalization, Opus compression, and silence-aware splitting (install a build with
libopus)
Installing Dependencies
yt-dlp (required):
# Using Homebrew (macOS)
brew install yt-dlp
# Using pip
pip install yt-dlp
ffmpeg (required for subtitle generation):
# Using Homebrew (macOS)
brew install ffmpeg
# Using apt (Ubuntu/Debian)
sudo apt install ffmpeg
Local Whisper (optional, for local subtitle generation):
pip install openai-whisper
Installation
From Source
git clone <repository-url>
cd transcript-mcp
npm install
npm run build
Global Installation (after publishing)
npm install -g transcript-mcp
Configuration
For Claude Desktop / Cursor
Add the MCP server to your configuration file:
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"transcript-mcp": {
"command": "node",
"args": ["/path/to/transcript-mcp/dist/index.js"],
"env": {
"TRANSCRIPT_MCP_STORAGE_DIR": "/path/to/downloads",
"OPENAI_API_KEY": "your-openai-api-key"
}
}
}
}
Cursor (~/.cursor/mcp.json):
{
"mcpServers": {
"transcript-mcp": {
"command": "node",
"args": ["/path/to/transcript-mcp/dist/index.js"],
"env": {
"TRANSCRIPT_MCP_STORAGE_DIR": "/path/to/downloads",
"OPENAI_API_KEY": "your-openai-api-key"
}
}
}
}
Environment Variables
| Variable | Description | Default |
|---|---|---|
TRANSCRIPT_MCP_STORAGE_DIR |
Default directory for downloaded videos | ~/.transcript-mcp/downloads |
OPENAI_API_KEY |
OpenAI API key for Whisper-based subtitle generation | None |
TRANSCRIPT_MCP_WHISPER_ENGINE |
Preferred whisper engine: openai, local, or auto |
auto |
VIDEO_TOOLKIT_STORAGE_DIR |
Legacy alias for TRANSCRIPT_MCP_STORAGE_DIR |
— |
VIDEO_TOOLKIT_WHISPER_ENGINE |
Legacy alias for TRANSCRIPT_MCP_WHISPER_ENGINE |
— |
WHISPER_BINARY_PATH |
Path to local whisper binary | whisper |
WHISPER_MODEL_PATH |
Path to whisper model (for local whisper) | Auto-download |
YT_DLP_PATH |
Path to yt-dlp binary | yt-dlp |
FFMPEG_PATH |
Path to ffmpeg binary | ffmpeg |
FFPROBE_PATH |
Path to ffprobe binary | Derived from FFMPEG_PATH |
TRANSCRIPT_MCP_URL_ALLOWLIST |
Comma-separated host patterns allowed for audio_url (e.g. *.amazonaws.com,localhost). Empty disables all audio_url fetches |
empty |
DEBUG |
Enable debug logging | 0 |
Usage
1. get-transcript
Retrieve existing transcripts from video platforms.
Parameters:
url(required): Video URLlang(optional): Language code (e.g., 'en', 'es', 'zh')include_timestamps(optional): Include timestamps (default: true)
Example:
Get the transcript from https://www.youtube.com/watch?v=VIDEO_ID
2. list-transcript-languages
List available transcript languages for a video.
Parameters:
url(required): Video URL
Example:
What transcript languages are available for https://www.youtube.com/watch?v=VIDEO_ID?
3. download-video
Download a video to local storage.
Parameters:
url(required): Video URL to downloadoutput_dir(optional): Custom output directoryfilename(optional): Custom filenameformat(optional): Video format -mp4,webm,mkv(default: mp4)quality(optional): Quality -best,1080p,720p,480p,360p,audio(default: best)
Example:
Download this video: https://www.youtube.com/watch?v=VIDEO_ID
4. list-downloads
List all downloaded video files.
Parameters:
directory(optional): Directory to list (default: storage directory)
Example:
List my downloaded videos
5. generate-subtitles
Generate subtitles for a local video file using AI speech-to-text.
Parameters:
video_path(required): Absolute path to the video fileengine(optional):openaiorlocal(default: auto-detect)language(optional): Language code for transcriptionoutput_format(optional):srtorvtt(default: srt)
Example:
Generate subtitles for /path/to/video.mp4
6. transcribe-audio
Transcribes audio via Whisper. Prefer audio_url (server fetches bytes; configure TRANSCRIPT_MCP_URL_ALLOWLIST). Use audio_base64 only for small clips (about 60KB raw per call; larger payloads should use chunked upload or a URL). audio_path / file:// only work when the MCP host shares a filesystem with the caller (often false in sandboxed clients).
By default the server re-encodes to Opus 16 kHz mono 16 kbps before Whisper. Set skip_compression: true if you already optimized the file.
Audio longer than 5 minutes (or when async: true) returns { job_id, status: "processing" }; poll transcribe_get_job.
Parameters (one required input):
audio_url,audio_path,audio_base64, oraudio_resource_uri(file:///data:...;base64,...)filename(optional): Hint when magic-byte detection is inconclusiveskip_compression(optional): Skip Opus recompression (default: false)engine(optional):openai,local, orauto(default:auto)language(optional): Language hint for transcriptioninclude_timestamps(optional): Whenas_textis true, include[MM:SS]lines (default: true)as_text(optional): If true, return plain transcript text; if false, return structured JSON (default: false)async(optional): Force async job (default: false)
Examples:
Transcribe this presigned URL (after allowlisting the host): audio_url=...
Transcribe this audio file on the MCP host: /path/to/interview.m4a
7. transcribeupload* (chunked upload)
For large files, split the raw bytes into base64 chunks of at most max_chunk_bytes (~60KB) from transcribe_upload_start, call transcribe_upload_append for each index, then transcribe_upload_finalize. Abandoned uploads are garbage-collected after about an hour.
8. transcribe_get_job / transcribe_cancel_job
Poll or cancel async jobs created by transcribe-audio (long audio or async: true).
Subtitle Generation Engines
OpenAI Whisper API
- Pros: High accuracy, no local setup needed, supports 50+ languages
- Cons: Requires API key, costs per audio minute
- Setup: Set
OPENAI_API_KEYenvironment variable
Local Whisper
- Pros: Free, runs locally, no API limits
- Cons: Requires setup, uses local CPU/GPU
- Setup:
pip install openai-whisper
The tool auto-detects which engine to use:
- If
OPENAI_API_KEYis set, uses OpenAI Whisper - If local whisper is installed, uses local whisper
- Returns an error if neither is available
For transcribe-audio, auto uses OpenAI first and falls back to local whisper when local whisper is available.
Example Workflows
Download and Generate Subtitles
1. Download this video: https://www.youtube.com/watch?v=VIDEO_ID
2. Generate subtitles for the downloaded file
Summarize a Video
Get the transcript from https://www.youtube.com/watch?v=VIDEO_ID and summarize the key points
Create Captions for Videos Without Subtitles
1. Download the video: https://vimeo.com/123456789
2. Generate English subtitles for it
Supported Platforms
Any platform supported by yt-dlp, including:
- YouTube
- Bilibili
- Vimeo
- Twitter/X
- TikTok
- Twitch
- And many more...
Full list: https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md
Project Structure
transcript-mcp/
├── src/
│ ├── index.ts # Main MCP server entry point
│ ├── transcript-fetcher.ts # Transcript fetching using yt-dlp
│ ├── video-downloader.ts # Video download functionality
│ ├── subtitle-generator.ts # AI-powered subtitle generation
│ ├── config.ts # Configuration management
│ ├── url-detector.ts # Platform detection from URLs
│ ├── parser.ts # Transcript parsing (SRT, VTT, JSON)
│ └── errors.ts # Custom error classes
├── test/
│ └── transcript.test.ts # Unit tests
├── dist/ # Compiled JavaScript (after build)
└── package.json
Development
# Build
npm run build
# Test
npm test
# Development mode
npm run dev
Troubleshooting
"yt-dlp is not installed"
brew install yt-dlp
# or
pip install yt-dlp
"ffmpeg is not installed"
brew install ffmpeg
"ffprobe is not installed"
brew install ffmpeg
"No Whisper engine available"
Either:
- Set
OPENAI_API_KEYenvironment variable, or - Install local whisper:
pip install openai-whisper
Download issues
- Check if the video is publicly accessible
- Some platforms may have rate limits
- Private/restricted videos cannot be downloaded
Subtitle generation is slow
- OpenAI Whisper API is faster than local
- Local whisper performance depends on your hardware
- Consider using a smaller model for local whisper
License
MIT
Acknowledgments
- yt-dlp for video platform support
- OpenAI Whisper for speech-to-text
- Model Context Protocol for the MCP framework
transcript MCP questions
What tools does transcript MCP provide?
It exposes 11 tools, including get-transcript, list-transcript-languages, download-video, list-downloads, generate-subtitles.
Which video platforms are supported?
The server works with YouTube, Bilibili, Vimeo, and any platform supported by yt-dlp.
How can I generate subtitles for a video?
You can use the generate-subtitles tool which utilizes either the OpenAI Whisper API or a local Whisper installation.
Can I transcribe large audio files?
Yes, for large audio payloads you can use chunked uploads via the transcribe_upload_start, append, and finalize tools.