YouTube MCP Server

A Model Context Protocol (MCP) server that enables AI agents to search and play YouTube videos through natural language commands.

Features

• searchVideos: Search YouTube for videos matching any query
• playPlaylist: Open videos in your default browser as a playlist

Prerequisites

1. Node.js 18+ installed
2. YouTube Data API v3 key from Google Cloud Console

Getting a YouTube API Key

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Navigate to APIs & Services > Library
4. Search for "YouTube Data API v3" and enable it
5. Go to APIs & Services > Credentials
6. Click Create Credentials > API Key
7. Copy your API key

Installation

1. Clone the repository
2. Install dependencies:

   npm install
   

3. Configure Environment Variables: Create a .env file in the root directory (copy from .env.example):

   cp .env.example .env
   

   Edit .env and add your YOUTUBE_API_KEY.
4. Build the project:

   npm run build
   

Add the following to your MCP configuration (e.g., .cursor/mcp.json or Claude Desktop config):

{
  "mcpServers": {
    "youtube-mcp": {
      "command": "node",
      "args": ["/path/to/your/project/youtubeMCP/dist/index.js"]
    }
  }
}

Note: The server will automatically load the YOUTUBE_API_KEY from the .env file in the project directory. Alternatively, you can pass it directly in the env object in the JSON config above.

Usage Examples

Once configured, you can ask your AI agent:

• "Search for 10 best English songs on YouTube"
• "Play 5 relaxing piano music videos"
• "Find Taylor Swift songs and play them"
• "Search for coding tutorials"

Available Tools

searchVideos

Search YouTube for videos by query.

Parameters:

• query (string, required): Search query
• maxResults (number, optional): Number of results (1-50, default: 10)

playPlaylist

Play videos in the browser.

Parameters:

• videoIds (string[], optional): Array of video IDs to play
• query (string, optional): Search and play videos matching this query
• maxResults (number, optional): Number of videos when using query (default: 10)

Development

# Watch mode for development
npm run dev

# Build
npm run build

# Start
npm start

Project Structure

YouTubeMCP/
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── youtube-client.ts  # YouTube API wrapper
│   └── tools/
│       ├── search.ts      # searchVideos tool
│       └── play.ts        # playPlaylist tool
└── dist/                  # Compiled JavaScript

License

MIT