YouTube Subtitles

YouTube Subtitles MCP Server lets AI assistants download and analyze YouTube video subtitles. It fetches video metadata and available subtitles in multiple languages, enabling you to summarize, translate, or study content with an MCP client.

How to use

Connect your MCP-compatible assistant to this server to access three core capabilities: retrieve video information, list available subtitle languages, and download subtitles in a chosen language. You can then ask your assistant to summarize, translate, or analyze the subtitles to better understand the video content.

How to install

Prerequisites you need before installing this MCP server are Python 3.10 or newer, yt-dlp, ffmpeg, an MCP-compatible client, and optional Docker for containerized deployment.

Using Docker (recommended) follow these steps.

git clone https://github.com/setkyar/youtube-subtitles-mcp.git
cd youtube-subtitles-mcp
docker build -t mcp/youtube-subtitles .

Manual installation steps if you are not using Docker.

git clone https://github.com/setkyar/youtube-subtitles-mcp.git
cd youtube-subtitles-mcp
pip install "mcp[cli]>=1.2.0" yt-dlp

# Install subtitle processing toolchain
# On Ubuntu/Debian
sudo apt-get install ffmpeg
# On macOS with Homebrew
# brew install ffmpeg
# On Windows, install ffmpeg from ffmpeg.org

Run the server after dependencies are installed.

python youtube_subtitles_server.py

Configuration for MCP client integration

You can configure an MCP client to connect to this server. The following example shows how Claude Desktop can be pointed to run the server in a container. This is the explicit MCP integration snippet your client will use.

{
  "mcpServers": {
    "youtube-subtitles": {
      "command": "docker",
      "args": ["run", "-i", "mcp/youtube-subtitles"]
    }
  }
}

Usage examples

Get video information: ask your assistant to fetch title, duration, and upload date for a YouTube video.

List available subtitle languages for a video: prompt your assistant with the video URL to see all languages supported.

Download and analyze subtitles: request subtitles in a specific language and have your assistant summarize or analyze the content.

Translate subtitles: ask for subtitles in one language and have them translated to another.

How it works

The server exposes three main tools to MCP clients: get_video_info, list_subtitle_languages, and download_subtitles. All operations leverage yt-dlp for robust YouTube subtitle handling.

Docker configuration and notes

The Docker-based setup uses Python 3.10 as the base image, installs ffmpeg for subtitle processing, and includes the necessary Python dependencies. The MCP server runs through a standard stdio transport.

Troubleshooting

Subtitles may not be available for all videos. If languages are missing, the video may only provide auto-generated subtitles. If you encounter Docker connection problems, ensure the container is running and your MCP client is configured to connect to it.

Logs can help diagnose issues. To view container logs, use the following command.

docker logs youtube-subtitles-mcp

Notes

This server supports downloading subtitles in any available language and retrieving video metadata such as title, duration, and upload date. It plays nicely with Claude Desktop and other MCP-compatible assistants when deployed via Docker or run directly with Python.

Tools and capabilities

• get_video_info: Retrieve basic metadata for a YouTube video.

• list_subtitle_languages: List all available subtitle languages for a video.

• download_subtitles: Download and format subtitles in a chosen language.

Available tools

get_video_info

Retrieve basic metadata for a YouTube video such as title, duration, and upload date.

list_subtitle_languages

List all available subtitle languages for a given video.

download_subtitles

Download and format subtitles in a specified language for analysis or translation.