READMEmain

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

serpapi-youtube-mcp-server