youtube-mcp

<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/> _{Scrape YouTube in your MCP clients — no official API key required} </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
• Features
• Quick Start
• Tools
• One-Click Install Prompt
• Client Setup
  • Cursor
  • Claude Code
  • Claude Desktop
  • OpenAI Codex
  • ChatGPT
• Examples
• How It Works
• FAQ
• 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

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

Or run directly with tsx:

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:

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

With Zyte proxy (optional):

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

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

CLI:

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

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

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

CLI:

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

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 © iamkw0n

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