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

# 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)

# 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

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

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)

# 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 工具

{
  "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

1. Open Claude Desktop
2. Go to Settings → Developer → Edit Config
3. Or edit the config file directly:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.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:

mcpServers:
  youtube-connector-mcp:
    command: youtube-connector-mcp
    env:
      YOUTUBE_API_KEY: "your_api_key_here"

---

API Key Setup

Set as Environment Variable (Recommended):

# Linux/Mac - Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export YOUTUBE_API_KEY="your_api_key_here"
source ~/.zshrc

# Windows PowerShell - Add to $PROFILE
$env:YOUTUBE_API_KEY="your_api_key_here"
# Or set permanently
[System.Environment]::SetEnvironmentVariable('YOUTUBE_API_KEY', 'your_api_key_here', 'User')

# Windows CMD
setx YOUTUBE_API_KEY "your_api_key_here"

Or Put Directly in MCP Config:

{
  "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

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable YouTube Data API v3
4. Go to Credentials and create an API key
5. (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:

1. Verify ~/.claude/mcp_config.json exists
2. Check JSON syntax is valid
3. Run claude mcp list to see registered servers
4. Restart Claude Code after updating config

Python Not Found

Error: command not found: python

Solutions:

1. Use python3 instead of python
2. Provide full path: which python3 (Mac/Linux) or where 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:

1. Check Google Cloud Console quota
2. Default: 10,000 units/day
3. Consider upgrading for higher limits

Transcript Not Available

Error: "No transcript available" or "Transcripts are disabled"

Solutions:

1. Video may not have captions enabled
2. Auto-generated captions may take 24+ hours after upload
3. 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

git clone https://github.com/ShellyDeng08/youtube-connector-mcp.git
cd youtube-connector-mcp
poetry install --with dev

Run Tests

poetry run pytest

Publishing to PyPI

# 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 C