YouTube Data MCP Server

YouTube Data MCP Server

A Model Context Protocol (MCP) server for extracting YouTube video transcripts, comments, and search results. Supports both Stdio and StreamableHTTP transports.

Features

• getTranscript - Extract subtitles/transcripts with optional timestamps
• getVideoInfo - Get video metadata (title, views, comments count)
• getComments - Fetch comments with pagination and sorting
• getCommentReplies - Get replies to specific comments
• searchYoutube - Search videos, channels, and playlists

What's New in v2.0

• Dual Transport: Stdio (default) + StreamableHTTP for web integration
• Reliable Transcripts: Replaced youtube-transcript with youtube-caption-extractor (bot detection bypass, serverless support)
• Timestamp Support: Optional start time and duration for each transcript segment
• Modular Architecture: Clean separation of concerns (config, types, services, tools)
• MCP SDK v1.25.2: Latest SDK with improved stability

Requirements

• Node.js 18+
• SerpAPI key (for search, comments, video info)

Installation

git clone https://github.com/diasm3/serpapi-youtube-mcp-server.git
cd serpapi-youtube-mcp-server
npm install

Configuration

Create a .env file:

SERPAPI_KEY=your_serpapi_key_here
PORT=3000  # optional, for HTTP mode

Get your SerpAPI key at serpapi.com.

Running the Server

# Build
npm run build

# Stdio mode (default) - for Claude Desktop, Cursor, etc.
npm start

# HTTP mode - for web applications
npm start -- --http
# or
MCP_TRANSPORT=http npm start

HTTP Endpoints

When running in HTTP mode:

• GET /health - Health check
• POST /mcp - MCP request handler

MCP Client Configuration

Claude Desktop / Cursor

{
  "mcpServers": {
    "youtube-data": {
      "command": "node",
      "args": ["/path/to/serpapi-youtube-mcp-server/build/index.js"],
      "env": {
        "SERPAPI_KEY": "your_serpapi_key_here"
      }
    }
  }
}

Using npx

{
  "mcpServers": {
    "youtube-data": {
      "command": "npx",
      "args": ["-y", "youtube-data-mcp"],
      "env": {
        "SERPAPI_KEY": "your_serpapi_key_here"
      }
    }
  }
}

API Tools

getTranscript

Extract transcript/subtitles from a YouTube video.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | Yes | YouTube URL or video ID | | lang | string | No | Language code (default: 'en') | | includeTimestamps | boolean | No | Include start/duration per segment |

Get the Korean transcript for https://youtube.com/watch?v=xxxxx with timestamps

getVideoInfo

Get video metadata using SerpAPI.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | Yes | YouTube URL or video ID |

Returns: title, views, publish date, channel, comment count, pagination tokens

getComments

Fetch video comments with pagination.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | Conditional | Required for first page | | limit | number | No | Max comments (default: 100) | | sort | string | No | 'relevance' or 'time' | | pageToken | string | No | For pagination |

getCommentReplies

Get replies to a specific comment.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | pageToken | string | Yes | repliesToken from comment |

searchYoutube

Search YouTube for videos, channels, playlists.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | Yes | Search query | | limit | number | No | Max results (default: 10) | | gl | string | No | Country code (us, kr, jp) | | hl | string | No | Language code (en, ko, ja) | | sp | string | No | Filter parameter | | pageToken | string | No | For pagination |

Project Structure

src/
├── index.ts          # Server entry (Stdio + HTTP)
├── config/           # Environment configuration
├── types/            # Zod schemas + TypeScript types
├── services/
│   ├── serpapi.ts    # SerpAPI integration
│   └── youtube.ts    # Transcript extraction
├── tools/            # MCP tool definitions
└── utils/            # Helper functions

Troubleshooting

Transcript not available

• Some videos don't have captions enabled
• Try different language codes (en, ko, ja, etc.)
• Auto-generated captions may not be available for all videos

SerpAPI errors

• Verify your API key is valid
• Check your SerpAPI quota/limits
• Ensure the video is publicly accessible

HTTP mode not starting

• Check if PORT is already in use
• Verify environment variables are set

License

MIT