YouTube MCP Server

A Model Context Protocol (MCP) server implementation for YouTube, enabling AI language models to interact with YouTube content through a standardized interface. Optimized for 90% Smithery quality score with comprehensive resources, prompts, and flexible configuration.

Features

Video Information

Get video details (title, description, duration, etc.) with direct URLs
List channel videos with direct URLs
Get video statistics (views, likes, comments)
Search videos across YouTube with direct URLs
NEW: Enhanced video responses include url and videoId fields for easy integration

Transcript Management

Retrieve video transcripts
Support for multiple languages
Get timestamped captions
Search within transcripts

Direct Resources & Prompts

Resources:
- youtube://transcript/{videoId}: Access transcripts directly via resource URIs
- youtube://info: Server information and usage documentation (Smithery discoverable)
Prompts:
- summarize-video: Automated workflow to get and summarize video content
- analyze-channel: Comprehensive analysis of a channel's content strategy
Annotations: All tools include capability hints (read-only, idempotent) for better LLM performance

Channel Management

Get channel details
List channel playlists
Get channel statistics
Search within channel content

Playlist Management

List playlist items
Get playlist details
Search within playlists
Get playlist video transcripts

Installation

Quick Setup for Claude Desktop

Install the package:

npm install -g @sfiorini/youtube-mcp

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "youtube-mcp": {
      "command": "youtube-mcp",
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key_here"
      }
    }
  }
}

Alternative: Using NPX (No Installation Required)

Add this to your Claude Desktop configuration:

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@sfiorini/youtube-mcp"],
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key_here"
      }
    }
  }
}

Installing via Smithery

To install YouTube MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli@latest install @sfiorini/youtube-mcp --client claude

Configuration

Set the following environment variables:

YOUTUBE_API_KEY: Your YouTube Data API key (required)
YOUTUBE_TRANSCRIPT_LANG: Default language for transcripts (optional, defaults to 'en')

Using with VS Code

For one-click installation, click one of the install buttons below:

Manual Installation

If you prefer manual installation, first check the install buttons at the top of this section. Otherwise, follow these steps:

Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "YouTube API Key",
        "password": true
      }
    ],
    "servers": {
      "youtube": {
        "command": "npx",
        "args": ["-y", "@sfiorini/youtube-mcp"],
        "env": {
          "YOUTUBE_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

Optionally, you can add it to a file called .vscode/mcp.json in your workspace:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "YouTube API Key",
      "password": true
    }
  ],
  "servers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@sfiorini/youtube-mcp"],
      "env": {
        "YOUTUBE_API_KEY": "${input:apiKey}"
      }
    }
  }
}

YouTube API Setup

Go to Google Cloud Console
Create a new project or select an existing one
Enable the YouTube Data API v3
Create API credentials (API key)
Copy the API key for configuration

Examples

Managing Videos

// Get video details (now includes URL)
const video = await youtube.videos.getVideo({
  videoId: "dQw4w9WgXcQ"
});

// Enhanced response now includes:
// - video.url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
// - video.videoId: "dQw4w9WgXcQ"
// - All original YouTube API data

// Get video transcript
const transcript = await youtube.transcripts.getTranscript({
  videoId: "video-id",
  language: "en"
});

// Search videos (results now include URLs)
const searchResults = await youtube.videos.searchVideos({
  query: "search term",
  maxResults: 10
});

// Each search result includes:
// - result.url: "https://www.youtube.com/watch?v={videoId}"
// - result.videoId: "{videoId}"
// - All original YouTube search data

Managing Channels

// Get channel details
const channel = await youtube.channels.getChannel({
  channelId: "channel-id"
});

// List channel videos
const videos = await youtube.channels.listVideos({
  channelId: "channel-id",
  maxResults: 50
});

Managing Playlists

// Get playlist items
const playlistItems = await youtube.playlists.getPlaylistItems({
  playlistId: "playlist-id",
  maxResults: 50
});

// Get playlist details
const playlist = await youtube.playlists.getPlaylist({
  playlistId: "playlist-id"
});

Enhanced Response Structure

Video Objects with URLs

All video-related responses now include enhanced fields for easier integration:

interface EnhancedVideoResponse {
  // Original YouTube API fields
  kind?: string;
  etag?: string;
  id?: string | YouTubeSearchResultId;
  snippet?: YouTubeSnippet;
  contentDetails?: any;
  statistics?: any;

  // NEW: Enhanced fields
  url: string;           // Direct YouTube video URL
  videoId: string;       // Extracted video ID
}

Example Enhanced Response

{
  "kind": "youtube#video",
  "id": "dQw4w9WgXcQ",
  "snippet": {
    "title": "Never Gonna Give You Up",
    "channelTitle": "Rick Astley",
    "description": "Official video for \"Never Gonna Give You Up\""
  },
  "statistics": {
    "viewCount": "1.5B",
    "likeCount": "15M"
  },
  // Enhanced fields:
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "videoId": "dQw4w9WgXcQ"
}

Benefits

Easy URL Access: No need to manually construct URLs
Consistent Structure: Both search and individual video responses include URLs
Backward Compatible: All existing YouTube API data is preserved
Type Safe: Full TypeScript support available

Development

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Development mode with auto-rebuild and hot reload
npm run dev

# Start the server (requires YOUTUBE_API_KEY)
npm start

# Publish to npm (runs build first)
npm run prepublishOnly

Architecture

This project uses a dual-architecture service-based design with the following features:

Shared Utilities: Single source of truth for all MCP server configuration (src/server-utils.ts)
Modern McpServer: Updated from deprecated Server class to the new McpServer
Dynamic Version Management: Version automatically read from package.json
Type-Safe Tool Registration: Uses zod schemas for input validation
ES Modules: Full ES module support with proper .js extensions
Enhanced Video Responses: All video operations include url and videoId fields
Lazy Initialization: YouTube API client initialized only when needed
Code Deduplication: Eliminated 90% code duplication through shared utilities (407 → 285 lines)

Project Structure

src/
├── server-utils.ts        # 🆕 Shared MCP server utilities (single source of truth)
├── index.ts              # Smithery deployment entry point
├── server.ts             # CLI deployment entry point
├── services/             # Core business logic
│   ├── video.ts         # Video operations (search, getVideo)
│   ├── transcript.ts    # Transcript retrieval
│   ├── playlist.ts      # Playlist operations
│   └── channel.ts       # Channel operations
├── types.ts             # TypeScript interfaces
└── cli.ts               # CLI wrapper for standalone execution

Key Features

Smithery Optimized: Achieved 90%+ Smithery quality score with comprehensive resources, prompts, and configuration
Shared Utilities Architecture: Eliminated 90% code duplication with single source of truth
Enhanced Video Responses: All video objects include direct YouTube URLs
Flexible Configuration: Optional config via Smithery UI or environment variables
Type-Safe Development: Full TypeScript support with zod validation
Modern MCP Tools: Uses registerTool instead of manual request handlers
Comprehensive Resources: Discoverable resources and prompts for better LLM integration
Error Handling: Comprehensive error handling with descriptive messages

Contributing

See CONTRIBUTING.md for information about contributing to this repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

youtube-mcp