Youtubemcp

🚀 YouTube MCP Server

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

🚀 Quick Start

The YouTube MCP Server is a powerful tool that enables AI agents to interact with YouTube through natural language. With this server, you can easily search for and play videos on YouTube.

✨ Features

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

📦 Installation

Prerequisites

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

Getting a YouTube API Key

1. Visit Google Cloud Console.
2. Create a new project (or select an existing one).
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 Steps

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"]
    }
  }
}

⚠️ Important 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).

🔧 Technical Details

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

This project is licensed under the MIT license.