# 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](https://console.cloud.google.com/marketplace/product/google/youtube.googleapis.com)
### Getting a YouTube API Key
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
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**:
```bash
npm install
```
3. **Configure Environment Variables**:
Create a `.env` file in the root directory (copy from `.env.example`):
```bash
cp .env.example .env
```
Edit `.env` and add your `YOUTUBE_API_KEY`.
4. **Build the project**:
```bash
npm run build
```
Add the following to your MCP configuration (e.g., `.cursor/mcp.json` or Claude Desktop config):
```json
{
"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
```bash
# 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
