yt-playlist-generator-mcp-server

# YouTube Playlist Generator MCP Server A Model Context Protocol (MCP) server that enables AI applications to search for YouTube music videos and manage playlists using the official YouTube Data API v3. ## Features - **Search Music Videos**: Find music videos on YouTube with customizable search parameters - **Get Video Details**: Retrieve comprehensive information about specific videos - **Get Playlist Items**: List videos from public playlists - **Playlist Management**: Complete playlist management including creating, editing, and managing playlists (requires OAuth setup) ## Setup ### Prerequisites - Node.js 18 or higher - A Google Cloud Project with YouTube Data API v3 enabled - YouTube Data API key - OAuth 2.0 Client credentials (optional, required for playlist management features) ### Installation 1. Clone this repository: ```bash git clone https://github.com/danisss9/yt-playlist-generator-mcp-server ``` 2. Install dependencies: ```bash npm install ``` 3. Get a YouTube Data API key: - Go to the [Google Cloud Console](https://console.cloud.google.com/) - Create a new project or select an existing one - Enable the YouTube Data API v3 - Create credentials (API key) - Copy the API key 4. Set up environment variables: ```bash # Create a .env file echo "YOUTUBE_API_KEY=your_api_key_here" > .env echo "YOUTUBE_CLIENT_ID=your_client_id_here" >> .env echo "YOUTUBE_CLIENT_SECRET=your_client_secret_here" >> .env ``` 5. Build the TypeScript code: ```bash npm run build ``` ### Running the Server For development with auto-rebuild: ```bash npm run dev ``` For production: ```bash npm start ``` ### Using with MCP Clients This server uses the stdio transport, so it can be used with any MCP client that supports stdio. #### Claude Desktop Configuration Add to your Claude Desktop configuration file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "youtube-playlist-generator": { "command": "node", "args": ["/absolute/path/to/yt-playlist-generator/build/index.js"], "env": { "YOUTUBE_API_KEY": "your_youtube_api_key_here", "YOUTUBE_CLIENT_ID": "your_client_id_here", "YOUTUBE_CLIENT_SECRET": "your_client_secret_here" } } } } ``` #### Visual Studio Code with GitHub Copilot Configuration To use this MCP server with GitHub Copilot in Visual Studio Code, you need to configure it in your VS Code settings: 1. **Open VS Code Settings**: Press `Ctrl+,` (Windows/Linux) or `Cmd+,` (macOS) 2. **Search for MCP**: Type "mcp" in the search bar 3. **Add MCP Server Configuration**: Add the following to your VS Code settings JSON: ```json { "github.copilot.chat.mcp.servers": { "youtube-playlist-generator": { "command": "node", "args": ["/absolute/path/to/yt-playlist-generator/build/index.js"], "env": { "YOUTUBE_API_KEY": "your_youtube_api_key_here", "YOUTUBE_CLIENT_ID": "your_client_id_here", "YOUTUBE_CLIENT_SECRET": "your_client_secret_here" } } } } ``` **Alternative: Use Settings UI** 1. Go to **File > Preferences > Settings** (or use `Ctrl+,`) 2. Search for "GitHub Copilot MCP" 3. Click "Edit in settings.json" next to "Github › Copilot › Chat: Mcp Servers" 4. Add the server configuration as shown above **Environment Variables Setup** For security, you can also set environment variables system-wide instead of in the config: **Windows (PowerShell)**: ```powershell [Environment]::SetEnvironmentVariable("YOUTUBE_API_KEY", "your_api_key_here", "User") [Environment]::SetEnvironmentVariable("YOUTUBE_CLIENT_ID", "your_client_id_here", "User") [Environment]::SetEnvironmentVariable("YOUTUBE_CLIENT_SECRET", "your_client_secret_here", "User") ``` **Windows (Command Prompt)**: ```cmd setx YOUTUBE_API_KEY "your_api_key_here" setx YOUTUBE_CLIENT_ID "your_client_id_here" setx YOUTUBE_CLIENT_SECRET "your_client_secret_here" ``` **macOS/Linux**: ```bash export YOUTUBE_API_KEY="your_api_key_here" export YOUTUBE_CLIENT_ID="your_client_id_here" export YOUTUBE_CLIENT_SECRET="your_client_secret_here" # Add to ~/.bashrc, ~/.zshrc, or ~/.profile to persist echo 'export YOUTUBE_API_KEY="your_api_key_here"' >> ~/.bashrc echo 'export YOUTUBE_CLIENT_ID="your_client_id_here"' >> ~/.bashrc echo 'export YOUTUBE_CLIENT_SECRET="your_client_secret_here"' >> ~/.bashrc ``` Then remove the `env` section from the VS Code configuration: ```json { "github.copilot.chat.mcp.servers": { "youtube-playlist-generator": { "command": "node", "args": ["/absolute/path/to/yt-playlist-generator/build/index.js"] } } } ``` **Usage in VS Code** Once configured, you can use the MCP server through GitHub Copilot Chat: 1. Open Copilot Chat (`Ctrl+Alt+I` or click the chat icon) 2. Use natural language to interact with YouTube: - "Search for music videos about jazz" - "Create a new playlist called 'My Favorites'" - "Add this video to my playlist" - "Show me details about this YouTube video" ## Available Tools ### Read-Only Tools (API Key Authentication) #### search_music_videos Search YouTube for music videos with specified criteria. **Parameters:** - `query` (string): Search query for music videos - `maxResults` (number, 1-50, default: 10): Maximum number of results - `order` (enum): Sort order - "relevance", "date", "rating", "viewCount", "title" #### get_video_details Get detailed information about a specific YouTube video. **Parameters:** - `videoId` (string): YouTube video ID #### get_playlist_items Retrieve videos from a public YouTube playlist. **Parameters:** - `playlistId` (string): YouTube playlist ID - `maxResults` (number, 1-50, default: 25): Maximum number of items ### OAuth-Required Tools (Playlist Management) #### authenticate_youtube Authenticate with YouTube OAuth to enable playlist management features. **Parameters:** - `getAuthUrl` (boolean, default: false): Set to true to get the authorization URL - `authCode` (string, optional): Authorization code from OAuth flow #### get_auth_status Check current OAuth authentication status. **Parameters:** None #### create_playlist Create a new YouTube playlist (requires OAuth authentication). **Parameters:** - `title` (string): Playlist title - `description` (string, optional): Playlist description - `privacy` (enum): "private", "public", or "unlisted" #### edit_playlist Edit existing playlist information (requires OAuth authentication). **Parameters:** - `playlistId` (string): ID of the playlist to edit - `title` (string, optional): New title for the playlist - `description` (string, optional): New description for the playlist - `privacy` (enum, optional): New privacy setting - "private", "public", or "unlisted" **Note:** At least one field (title, description, or privacy) must be provided to update. #### add_to_playlist Add a video to an existing playlist (requires OAuth authentication). **Parameters:** - `playlistId` (string): Target playlist ID - `videoId` (string): Video ID to add #### list_playlists List user's playlists (requires OAuth authentication). **Parameters:** - `maxResults` (number, 1-50, default: 25): Maximum number of playlists - `mine` (boolean, default: true): List authenticated user's playlists #### remove_from_playlist Remove a video from a playlist (requires OAuth authentication). **Parameters:** - `playlistItemId` (string): ID of the playlist item to remove (get from get_playlist_items) ## OAuth Authentication Setup For full playlist management capabilities, you need to set up OAuth 2.0: ### 1. Google Cloud Console Setup 1. Go to [Google Cloud Console](https://console.cloud.google.com/) 2. Create a new project or select existing one 3. Enable the YouTube Data API v3 4. Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client ID" 5. Choose "Desktop Application" as application type 6. Download the credentials or copy the Client ID and Client Secret ### 2. Environment Configuration Add your OAuth credentials to the `.env` file: ```bash YOUTUBE_API_KEY=your_api_key_here YOUTUBE_CLIENT_ID=your_client_id_here YOUTUBE_CLIENT_SECRET=your_client_secret_here ``` ### 3. Authentication Flow 1. Use the `authenticate_youtube` tool with `getAuthUrl: true` 2. Open the provided URL in your browser 3. Sign in to your Google account and grant permissions 4. Copy the authorization code 5. Use `authenticate_youtube` tool again with the `authCode` parameter ### 4. Using Authenticated Features Once authenticated, you can: - Create new playlists - Edit existing playlist information (title, description, privacy) - Add videos to your playlists - List your private playlists - Remove videos from playlists ## API Limitations - **Quota Limits**: YouTube API has daily quota limits (10,000 units/day by default) - **Rate Limiting**: API calls are subject to rate limiting - **OAuth Tokens**: Access tokens expire and need refresh (handled automatically) - **Permissions**: OAuth scope determines available operations ## Development ### Building ```bash npm run build ``` ### Development Mode ```bash npm run dev ``` ### Project Structure ``` src/ └── index.ts # Main server implementation build/ # Compiled JavaScript output ``` ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Test thoroughly 5. Submit a pull request ## License MIT License - see LICENSE file for details ## Troubleshooting ### Common Issues 1. **"YOUTUBE_API_KEY environment variable is required"** - Make sure you've set the YOUTUBE_API_KEY environment variable - Verify the API key is valid and has YouTube Data API access 2. **"Quota exceeded" errors** - You've hit the daily API quota limit - Wait for quota reset or request quota increase 3. **"Playlist not found" errors** - Ensure the playlist ID is correct - Verify the playlist is public (private playlists require OAuth) 4. **Build errors** - Make sure you have Node.js 18+ installed - Run `npm install` to ensure all dependencies are installed - Check TypeScript compilation with `npm run build` ## Security Considerations - Never commit API keys to version control - Use environment variables for sensitive configuration - Validate all user inputs - Implement proper error handling and logging --- *This project was created using GitHub Copilot*