# YouTube MCP Server (youtube-connector-mcp)

[![MCP Badge](https://lobehub.com/badge/mcp/shellydeng08-youtube-connector-mcp)](https://lobehub.com/mcp/shellydeng08-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](https://www.python.org/downloads/) or `brew install python3`                                                                                                                         |
| **YouTube API Key** | Get it free from [Google Cloud Console](https://console.cloud.google.com/apis/credentials)                                                                                                             |
| **MCP Client**      | Any MCP-compatible AI: [Claude](https://claude.com/code), [Cursor](https://cursor.sh), [Cline](https://cline.so), [Windsurf](https://codeium.com/windsurf), [Continue.dev](https://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](#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

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`

```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
[System.Environment]::SetEnvironmentVariable('YOUTUBE_API_KEY', 'your_api_key_here', 'User')
```

```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

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable [YouTube Data API v3](https://console.cloud.google.com/apis/library)
4. Go to [Credentials](https://console.cloud.google.com/apis/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](https://console.cloud.google.com/apis/api/youtube.googleapis.com/quotas)
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](https://github.com/jdepoix/youtube-transcript-api?tab=readme-ov-file#working-around-ip-bans-requestblocked-or-ipblocked-exception) 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](LICENSE) for details.

---

## Links

- [Official Website](https://youtube-connector-mcp-website.vercel.app/)
- [GitHub Repository](https://github.com/ShellyDeng08/youtube-connector-mcp)
- [PyPI Package](https://pypi.org/project/youtube-connector-mcp/)
- [YouTube Data API v3 Docs](https://developers.google.com/youtube/v3)
- [Claude Code](https://claude.com/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