YouTube MCP Server (youtube-connector-mcp)
youtube-connector-mcp is a YouTube MCP Server / Connector that allows AI assistants like Claude, Cursor, Cline, Windsurf, Continue.dev, Grapes AI to interact with the YouTube Data API v3 via the Model Context Protocol (MCP).
🌐 Project Website: https://youtube-connector-mcp-website.vercel.app/
📦 PyPI Package: https://pypi.org/project/youtube-connector-mcp/
Quick Start```bash
1. Get your YouTube API Key from Google Cloud Console
https://console.cloud.google.com/apis/credentials
2. Set your API key as environment variable
export YOUTUBE_API_KEY="your_api_key_here"
3. Install pipx first (if not installed)
brew install pipx # macOS
or: apt install pipx # Ubuntu/Debian
4. Install the package
pipx install youtube-connector-mcp
5. Add the MCP server
claude mcp add youtube-connector-mcp youtube-connector-mcp -s user -e YOUTUBE_API_KEY="${YOUTUBE_API_KEY}"
6. Restart Claude Code and start using!
---
## Prerequisites
| Requirement | How to Get |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Python 3.10+** | Download Python or `brew install python3` |
| **YouTube API Key** | Get it free from Google Cloud Console |
| **MCP Client** | Any MCP-compatible AI: Claude, Cursor, Cline, Windsurf, Continue.dev, etc. |
---
## Installation
### Install from PyPI (Recommended)```bash
# Install pipx first (if not installed)
brew install pipx # macOS
# or: apt install pipx # Ubuntu/Debian
# Then install the package
pipx install youtube-connector-mcp
# Or with pip in a virtual environment
python3 -m venv .venv
source .venv/bin/activate
pip install youtube-connector-mcp
Install from Source```bash
git clone https://github.com/ShellyDeng08/youtube-connector-mcp.git
cd youtube-connector-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
### Verify Installation```bash
youtube-connector-mcp --help
claude mcp list # Check if server is registered
Configuration
Popular AI Coding Tools
| Tool | Platform | Config |
|---|---|---|
| Claude Code | CLI | claude mcp add |
| Claude Desktop | macOS/Windows | claude_desktop_config.json |
| Cursor IDE | Desktop | Settings UI |
| Cline | VS Code Extension | .cline/config.yaml |
> Note: Any MCP-compatible AI tool works! Just use the standard JSON config format below.
Option 1: Using claude mcp add (Claude Code - Easiest)```bash
Install for current project only
claude mcp add youtube-connector-mcp youtube-connector-mcp -s local -e YOUTUBE_API_KEY="${YOUTUBE_API_KEY}"
Install for all your projects (recommended)
claude mcp add youtube-connector-mcp youtube-connector-mcp -s user -e YOUTUBE_API_KEY="${YOUTUBE_API_KEY}"
Install to project's .mcp.json
claude mcp add youtube-connector-mcp youtube-connector-mcp -s project -e YOUTUBE_API_KEY="${YOUTUBE_API_KEY}"
> **Don't have an API key?** See Creating a YouTube API Key below - it's free and takes just a few minutes.
---
### Option 2: Standard JSON Configuration
**适用于任何 MCP 兼容的 AI 工具**```json
{
"mcpServers": {
"youtube-connector-mcp": {
"command": "youtube-connector-mcp",
"env": {
"YOUTUBE_API_KEY": "your_api_key_here"
}
}
}
}
各工具配置文件位置:
| Tool | Config File Path |
|---|---|
| Claude Code | ~/.claude/mcp_config.json |
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) |
| Cursor IDE | Settings → MCP Servers (UI) |
| Cline (VS Code) | .cline/config.yaml |
Option 3: Claude Desktop
- Open Claude Desktop
- Go to Settings → Developer → Edit Config
- Or edit the config file directly:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows: `%APPDATA%\Claude\claude_desktop_config.json````json
{
"mcpServers": {
"youtube-connector-mcp": {
"command": "youtube-connector-mcp",
"env": {
"YOUTUBE_API_KEY": "your_api_key_here"
}
}
}
}
### Option 4: Cursor IDE
1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Go to **MCP Servers** section
3. Add a new server using the JSON format above
### Option 5: Cline (VS Code Extension)
Add to your `.cline/config.yaml`:```yaml
mcpServers:
youtube-connector-mcp:
command: youtube-connector-mcp
env:
YOUTUBE_API_KEY: "your_api_key_here"
API Key Setup
Set as Environment Variable (Recommended):```bash
Linux/Mac - Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export YOUTUBE_API_KEY="your_api_key_here"
source ~/.zshrc
``````powershell
Windows PowerShell - Add to $PROFILE
$env:YOUTUBE_API_KEY="your_api_key_here"
Or set permanently
``````cmd
Windows CMD
setx YOUTUBE_API_KEY "your_api_key_here"
**Or Put Directly in MCP Config:**```json
{
"mcpServers": {
"youtube-connector-mcp": {
"command": "youtube-connector-mcp",
"env": {
"YOUTUBE_API_KEY": "AIzaSyC-Your-Actual-API-Key-Here"
}
}
}
}
> Security Note: Using environment variables is safer as it keeps your key out of version control.
Creating a YouTube API Key
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable YouTube Data API v3
- Go to Credentials and create an API key
- (Optional) Restrict the key to YouTube Data API v3 for better security
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
YOUTUBE_API_KEY |
Yes | - | YouTube Data API v3 key |
YOUTUBE_RATE_LIMIT |
No | 100 | Max requests per second |
Features
Core Capabilities
| Tool | Description |
|---|---|
youtube_search |
Search videos, channels, playlists with filters (duration, date, type, order) |
youtube_get_video |
Get detailed video metadata, statistics, thumbnails, and content details |
youtube_get_channel |
Get channel info, subscriber count, upload playlists, statistics |
youtube_get_transcript |
Retrieve actual video transcript text with timestamps |
youtube_get_comments |
Fetch video comments with pagination support |
youtube_get_playlist |
Get playlist details and complete video list |
youtube_list_playlists |
List all playlists for a specific channel |
Use Cases
- Research: Search and analyze YouTube content programmatically
- Content Analysis: Extract transcripts and comments for AI processing
- Channel Monitoring: Track channel statistics and new uploads
- Data Mining: Gather YouTube data for your projects
- Automated Workflows: Integrate YouTube data into AI-assisted workflows
Usage Examples
| Category | Example Prompts |
|---|---|
| Search | "Search for Python tutorials" / "Find recent AI videos" / "Channels about cooking with 100k+ subscribers" |
| Video | "Get details for this video: URL" / "What's the view count?" / "Get the transcript" |
| Channel | "How many subscribers does @MKBHD have?" / "Recent uploads from this channel" / "Channel statistics" |
| Playlist | "List all playlists for this channel" / "Get videos in this playlist" |
Troubleshooting
MCP Server Not Found
Error:
No MCP servers configured
Solutions:
- Verify
~/.claude/mcp_config.jsonexists - Check JSON syntax is valid
- Run
claude mcp listto see registered servers - Restart Claude Code after updating config
Python Not Found
Error:
command not found: python
Solutions:
- Use
python3instead ofpython - Provide full path:
which python3(Mac/Linux) orwhere python(Windows)
Module Not Found
Error:
ModuleNotFoundError: No module named 'mcp'
Solutions:
- If using pipx:
pipx reinstall youtube-connector-mcp - If using pip in venv: Activate virtual environment first
source .venv/bin/activate
API Quota Exceeded
Error:
403 Forbidden - quota exceeded
Solutions:
- Check Google Cloud Console quota
- Default: 10,000 units/day
- Consider upgrading for higher limits
Transcript Not Available
Error: "No transcript available" or "Transcripts are disabled"
Solutions:
- Video may not have captions enabled
- Auto-generated captions may take 24+ hours after upload
- Try a video known to have captions
Transcript Request Blocked
Error: "YouTube is blocking requests from your IP"
Solutions:
See youtube-transcript-api documentation for proxy options.
Development
Setup```bash
git clone https://github.com/ShellyDeng08/youtube-connector-mcp.git
cd youtube-connector-mcp
poetry install --with dev
### Run Tests```bash
poetry run pytest
Publishing to PyPI```bash
Bump version (PyPI doesn't allow re-uploading the same version)
poetry version patch # 0.3.0 → 0.3.1
poetry version minor # 0.3.0 → 0.4.0
poetry version major # 0.3.0 → 1.0.0
Build and publish
poetry build
poetry publish
```
License
MIT License - see LICENSE for details.
Links
- Official Website
- GitHub Repository
- PyPI Package
- YouTube Data API v3 Docs
- Claude Code
SEO Keywords
YouTube MCP Server, YouTube MCP Connector, MCP YouTube API, Claude MCP YouTube, Cursor MCP YouTube, AI YouTube API, Model Context Protocol YouTube