<p align="center">
  <img src="https://capsule-render.vercel.app/api?type=waving&color=0:ff0000,100:cc0000&height=120&section=header&text=youtube-mcp&fontSize=42&fontColor=ffffff&animation=fadeIn" alt="youtube-mcp" />
</p>

<p align="center">
  <b>YouTube video search · channels · playlists · comments</b><br/>
  <sub>Scrape YouTube in your MCP clients — no official API key required</sub>
</p>

<p align="center">
  <a href="https://github.com/iamkw0n/youtube-mcp/stargazers"><img src="https://img.shields.io/github/stars/iamkw0n/youtube-mcp?style=for-the-badge&logo=github&color=cc0000" alt="Stars"/></a>
  <a href="https://github.com/iamkw0n/youtube-mcp/network/members"><img src="https://img.shields.io/github/forks/iamkw0n/youtube-mcp?style=for-the-badge&logo=github&color=cc0000" alt="Forks"/></a>
  <a href="https://github.com/iamkw0n/youtube-mcp/issues"><img src="https://img.shields.io/github/issues/iamkw0n/youtube-mcp?style=for-the-badge&logo=github&color=cc0000" alt="Issues"/></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-cc0000?style=for-the-badge" alt="License"/></a>
</p>

<p align="center">
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-stdio-cc0000?style=flat-square&logo=anthropic" alt="MCP"/></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node"/></a>
  <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"/></a>
  <a href="https://www.youtube.com"><img src="https://img.shields.io/badge/source-www.youtube.com-ff0000?style=flat-square&logo=youtube&logoColor=white" alt="YouTube"/></a>
</p>

<p align="center">
  <a href="#-quick-start">Quick Start</a>
  ·
  <a href="#-tools">Tools</a>
  ·
  <a href="#-client-setup">Client Setup</a>
  ·
  <a href="#-examples">Examples</a>
  ·
  <a href="#-faq">FAQ</a>
  ·
  <a href="https://github.com/iamkw0n/youtube-mcp/issues/new">Report Bug</a>
</p>

---

<details>
<summary><b>📑 Table of contents (Click to show)</b></summary>

- [Important Notices](#-important-notices)
- [Features](#-features)
- [Quick Start](#-quick-start)
- [Tools](#-tools)
- [One-Click Install Prompt](#-one-click-install-prompt)
- [Client Setup](#-client-setup)
  - [Cursor](#cursor)
  - [Claude Code](#claude-code)
  - [Claude Desktop](#claude-desktop)
  - [OpenAI Codex](#openai-codex)
  - [ChatGPT](#chatgpt)
- [Examples](#-examples)
- [How It Works](#-how-it-works)
- [FAQ](#-faq)
- [License](#-license)

</details>

---

## ⚠️ Important Notices

> [!IMPORTANT]
> This project **does not use the official YouTube Data API v3**. It parses public web pages (`ytInitialData`). If YouTube changes its page structure, some features may break. **Personal, non-commercial use** is recommended.

> [!WARNING]
> Excessive requests may get blocked by YouTube. If that happens often, enable the Zyte proxy with the `ZYTE_API_KEY` environment variable.

---

## ✨ Features

| | |
| :--- | :--- |
| 🔍 **Video search** | Keyword search with sort, date, and duration filters |
| 📺 **Video details** | Views, likes, duration, and more by ID or URL |
| 📡 **Channels** | Look up channels by ID, @handle, or URL |
| 📋 **Playlists** | Playlist metadata and video lists |
| 💬 **Comments** | Top and recent comments on a video |
| 🔌 **stdio MCP** | Works with Cursor, Claude, Codex, and other local clients |
| 🔑 **No API key** | No Google Cloud API key required |

---

## 🚀 Quick Start

```bash
git clone https://github.com/iamkw0n/youtube-mcp.git
cd youtube-mcp
npm install
npm run build
npm start
```

Or run directly with tsx:

```bash
npx tsx src/index.ts
```

---

## 🛠 Tools

| Tool | Description |
| :--- | :--- |
| `search_videos` | Search videos by keyword |
| `get_video` | Get video details by ID or URL |
| `get_videos` | Batch-fetch multiple videos |
| `search_channels` | Search channels by keyword |
| `get_channel` | Get channel info by ID, @handle, or URL |
| `get_channel_videos` | List recent videos from a channel |
| `get_playlist` | Get playlist metadata |
| `get_playlist_items` | List videos in a playlist |
| `get_video_comments` | Fetch video comments |
| `api_status` | Check scraping and proxy status |

---

## 💬 One-Click Install Prompt

Paste this into Cursor, Claude Code, or Codex to ask the agent to install the MCP server:

```
Clone iamkw0n/youtube-mcp from GitHub and set up the MCP server for me.
```

---

## 🔧 Client Setup

| Client | Config file | stdio |
| :--- | :--- | :---: |
| Cursor | `.cursor/mcp.json` | ✅ |
| Claude Code | `.mcp.json` | ✅ |
| Claude Desktop | `claude_desktop_config.json` | ✅ |
| Codex | `.codex/config.toml` | ✅ |
| ChatGPT | Connector URL | ❌ |

### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "youtube-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/youtube-mcp"
    }
  }
}
```

With Zyte proxy (optional):

```json
{
  "mcpServers": {
    "youtube-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/youtube-mcp",
      "env": {
        "ZYTE_API_KEY": "${env:ZYTE_API_KEY}"
      }
    }
  }
}
```

### Claude Code

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "youtube-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/youtube-mcp/dist/index.js"]
    }
  }
}
```

CLI:

```bash
claude mcp add youtube-mcp -s project -- node /absolute/path/to/youtube-mcp/dist/index.js
```

### Claude Desktop

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "youtube-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/youtube-mcp"
    }
  }
}
```

> [!WARNING]
> Claude Desktop does not support `${workspaceFolder}`. Use **absolute paths**.

### OpenAI Codex

In `.codex/config.toml` or `~/.codex/config.toml`:

```toml
[mcp_servers.youtube-mcp]
command = "node"
args = ["/absolute/path/to/youtube-mcp/dist/index.js"]
cwd = "/absolute/path/to/youtube-mcp"
enabled = true
```

CLI:

```bash
codex mcp add youtube-mcp -- node /absolute/path/to/youtube-mcp/dist/index.js
```

Verify in a Codex session with `/mcp`.

### ChatGPT

> [!IMPORTANT]
> ChatGPT connectors only support **HTTPS MCP endpoints**. This repo is a local **stdio** server and cannot be connected to ChatGPT directly.

---

## 💡 Examples

```
Search YouTube for TypeScript tutorial videos
```

```
Get details for this video: https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

```
Show me the 5 most recent videos from @GoogleDevelopers
```

```
What videos are in this playlist? https://www.youtube.com/playlist?list=PL...
```

---

## ⚙️ How It Works

```mermaid
flowchart LR
    A[MCP Client] -->|stdio| B[youtube-mcp]
    B -->|fetch HTML| C[www.youtube.com]
    B -->|parse| D[ytInitialData]
    B -->|pagination| E[InnerTube continuation]
```

| Step | Description |
| :--- | :--- |
| Page fetch | Download public YouTube HTML pages |
| Data extraction | Parse `ytInitialData` and `ytInitialPlayerResponse` JSON |
| Pagination | Load more results via InnerTube continuation tokens |

---

## 📄 License

[MIT](./LICENSE) © iamkw0n

<p align="center">
  <sub>Built with ❤️ by <a href="https://github.com/iamkw0n">iamkw0n</a> · Unofficial project, not affiliated with YouTube or Google</sub>
</p>