# 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