# youtube-subtitle-mcp
## 基本信息
- Slug: `guangxiangdebizi-youtube-subtitle-mcp`
- Source: modelscope
- Publisher: @guangxiangdebizi/youtube-subtitle-mcp
- Categories: multimedia-processing / entertainment-and-media / web-scraping
- Hosted: No
- License: Other
- Source URL: https://www.modelscope.cn/mcp/servers/@guangxiangdebizi/youtube-subtitle-mcp
## 简介
暂无描述。
## 安装提示

```bash
npx -y youtube-subtitle-mcp
```

## MCP Server 详情

#  YouTube Subtitle MCP Server

A Model Context Protocol (MCP) server for fetching YouTube video subtitles/transcripts with support for multiple output formats (SRT, VTT, TXT, JSON).

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-0.6.0-green.svg)](https://modelcontextprotocol.io)

##  Features

-  Fetch subtitles from any public YouTube video
-  Multiple output formats: SRT, VTT, TXT, JSON
-  Multi-language subtitle support
-  Two deployment modes: stdio (local) and HTTP (server)
-  Zero-configuration setup with npx
-  Complete timestamp information
-  Production-ready with TypeScript
-  Built with youtubei.js for reliable and stable subtitle extraction

##  Quick Start

###  Method 1: stdio Mode (Recommended for Local Use)

**Zero configuration required!** Simply use npx:

```bash
npx -y youtube-subtitle-mcp
```

Or install globally:

```bash
npm install -g youtube-subtitle-mcp
youtube-subtitle-mcp
```

###  Method 2: HTTP Mode (For Server Deployment)

```bash
# Clone repository
git clone https://github.com/guangxiangdebizi/youtube-subtitle-mcp.git
cd youtube-subtitle-mcp

# Install dependencies
npm install

# Build
npm run build

# Start HTTP server
npm run start:http
```

Server will start at `http://localhost:3000`

##  Installation

### For Development

```bash
# Clone repository
git clone https://github.com/guangxiangdebizi/youtube-subtitle-mcp.git
cd youtube-subtitle-mcp

# Install dependencies
npm install

# Build
npm run build
```

### For Production

```bash
npm install -g youtube-subtitle-mcp
```

##  Configuration

###  stdio Mode Configuration (Recommended)

Add to your MCP client configuration file:

**Claude Desktop / Cursor Configuration:**

- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "youtube-subtitle": {
      "command": "npx",
      "args": ["-y", "youtube-subtitle-mcp"]
    }
  }
}
```

**For local development:**

```json
{
  "mcpServers": {
    "youtube-subtitle": {
      "command": "node",
      "args": ["C:/path/to/youtube-subtitle-mcp/build/index.js"]
    }
  }
}
```

###  HTTP Mode Configuration

```json
{
  "mcpServers": {
    "youtube-subtitle": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp",
      "timeout": 600
    }
  }
}
```

##  Tool: fetch_youtube_subtitles

### Parameters

| Parameter | Type | Required | Description | Example |
|-----------|------|----------|-------------|---------|
| `url` | string |  Yes | YouTube video URL or video ID | `https://www.youtube.com/watch?v=dQw4w9WgXcQ` |
| `format` | string |  No | Output format (default: JSON) | `SRT`, `VTT`, `TXT`, `JSON` |
| `lang` | string |  No | Language code (default: auto) | `zh-Hans`, `en`, `ja` |

### Supported URL Formats

- Standard: `https://www.youtube.com/watch?v=VIDEO_ID`
- Short: `https://youtu.be/VIDEO_ID`
- Embed: `https://www.youtube.com/embed/VIDEO_ID`
- Direct ID: `VIDEO_ID`

### Language Codes

- `zh-Hans` - Simplified Chinese
- `zh-Hant` - Traditional Chinese
- `en` - English
- `ja` - Japanese
- `ko` - Korean
- `es` - Spanish
- `fr` - French
- `de` - German

##  Usage Examples

### Example 1: Fetch JSON Format Subtitles (Default)

```
Please fetch subtitles from this video:
https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

### Example 2: Fetch SRT Format Subtitles

```
Please fetch subtitles in SRT format from:
https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

### Example 3: Fetch Specific Language Subtitles

```
Please fetch Simplified Chinese subtitles in VTT format from:
https://www.youtube.com/watch?v=dQw4w9WgXcQ
Language code: zh-Hans
```

### Example 4: Fetch Plain Text Content

```
Please fetch plain text subtitles from:
https://youtu.be/dQw4w9WgXcQ
Format: TXT
```

##  Output Format Examples

### JSON Format

```json
[
  {
    "text": "Hello world",
    "start": 0,
    "end": 2000,
    "duration": 2000
  },
  {
    "text": "Welcome to YouTube",
    "start": 2000,
    "end": 5000,
    "duration": 3000
  }
]
```

### SRT Format

```srt
1
00:00:00,000 --> 00:00:02,000
Hello world

2
00:00:02,000 --> 00:00:05,000
Welcome to YouTube
```

### VTT Format

```vtt
WEBVTT

00:00:00.000 --> 00:00:02.000
Hello world

00:00:02.000 --> 00:00:05.000
Welcome to YouTube
```

### TXT Format

```text
Hello world
Welcome to YouTube
This is a subtitle example
```

##  Project Structure

```
youtube-subtitle-mcp/
 src/
    index.ts              # stdio mode entry (recommended for local use)
    httpServer.ts         # HTTP mode entry (for server deployment)
    tools/
        fetchYoutubeSubtitles.ts  # Main tool implementation
        formatters.ts     # Format converters (SRT/VTT/TXT/JSON)
        utils.ts          # Utility functions
 build/                    # Compiled JavaScript (generated)
 package.json
 tsconfig.json
 README.md
```

##  Development

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run watch
```

### Start stdio Mode

```bash
npm run start:stdio
```

### Start HTTP Mode

```bash
npm run start:http
```

### Custom Port (HTTP Mode)

```bash
PORT=8080 npm run start:http
```

##  Docker Deployment

### Using Docker

```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "run", "start:http"]
```

```bash
# Build image
docker build -t youtube-subtitle-mcp .

# Run container
docker run -d -p 3000:3000 --name youtube-mcp youtube-subtitle-mcp
```

### Using Docker Compose

```yaml
version: '3.8'
services:
  youtube-subtitle-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
    restart: unless-stopped
```

```bash
docker-compose …