MCP YouTube Server

This is a simple Model Context Protocol (MCP) server that provides tools to interact with YouTube. It allows an MCP host application (like Claude for Desktop) to:

• Search for YouTube videos.
• Get detailed information about specific YouTube videos.

Requirements

• Python 3.10 or higher.
• uv (must be installed before running setup).
• A YouTube Data API v3 Key. You can obtain one from the Google Cloud Console.
• bash compatible shell (for running the setup script, primarily Linux/macOS).

Installation & Setup

1. Clone the repository:

   git clone https://github.com/davo00019/mcp-server-youtube.git
   cd mcp-server-youtube
   

2. Run the setup script:

   • Ensure you have uv installed (pip install uv or see uv installation).
   • From within the mcp-server-youtube directory, run:

     bash setup.sh
     

   • The script will:
     • Check for uv.
     • Create a virtual environment (.venv) inside mcp-server-youtube.
     • Install dependencies (uv sync).
     • Prompt you for your YouTube API Key and create the .env file.
     • Make the server wrapper script executable.
     • Print the final instructions and the path needed for your MCP host configuration.

3. Configure MCP Host:

   • Follow the instructions printed at the end of the setup.sh script.
   • Copy the 'Wrapper Script Path' provided by the script.
   • Paste this path into your MCP host's configuration file (e.g., claude_desktop_config.json) as the command for the youtube server, ensuring the args are [].

Configuration Details (.env)

The setup.sh script will prompt you for your YouTube Data API v3 key and create a .env file in the mcp-server-youtube directory with the following content:

YOUTUBE_API_KEY=YOUR_API_KEY_HERE

If you need to change the key later, you can edit this .env file directly.

Running with an MCP Host (Example: Claude for Desktop)

After running the setup.sh script and configuring your MCP host as described above (Step 3 in Installation & Setup), the server should launch automatically when your host application starts.

1. Find your Claude for Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Edit the config file: Update the mcpServers section. The setup.sh script (via print_config_paths.py) provides an example JSON structure showing exactly how to configure the youtube server entry, including the correct absolute path for the command field. Copy and paste or adapt the example from the script's output into your configuration file.

3. Restart Claude for Desktop.

   • Windows Users Note: The setup.sh and run_server.sh scripts are designed for bash environments (Linux/macOS). You might need to perform the setup steps manually (create venv, install deps, create .env, configure host with direct python/script paths) or adapt the scripts for Windows (e.g., create a run_server.bat).

Usage

Once the server is configured in your MCP host and the host is restarted, the YouTube tools should become available. You can then use natural language prompts within the host application:

• "Search YouTube for 'python async tutorial'"
• "Find videos about 'MCP server development'"
• "Get the details for YouTube video ID XXXXXXX" (Replace XXXXXXX with a valid ID)

The host application will communicate with the local youtube_server.py process to fulfill these requests.

Available Tools

The server currently provides the following tools:

• search_videos(query: str, max_results: int = 5): Searches YouTube for videos based on a query string.
• get_video_details(video_id: str): Fetches detailed information (snippet, statistics, content details) for a specific video ID.
• get_channel_details(channel_id: str): Fetches detailed information (snippet, statistics) for a specific channel ID.
• list_channel_videos(channel_id: str, max_results: int = 10): Lists recent videos uploaded by a specific channel ID.
• search_playlists(query: str, max_results: int = 5): Searches YouTube for playlists matching a query string.
• get_playlist_items(playlist_id: str, max_results: int = 10): Lists the videos contained within a specific playlist ID.
• get_related_videos(video_id: str, max_results: int = 5): Finds videos that YouTube deems related to a given video ID.
• get_popular_videos(region_code: str = 'US', video_category_id: str = '0', max_results: int = 10): Lists the most popular videos currently trending in a specific region or category.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests if you have improvements or bug fixes.

License

This project is licensed under the MIT License - see the LICENSE file for details.