YouTube for AI Agents

Give your AI coding agent the ability to use YouTube — search for videos, watch and analyze content, browse channels, and explore playlists. Built on MCP, works with Claude Code and other compatible agents.

Tools

Tool	Description
youtube_search	Search YouTube for videos, channels, or playlists. Filter by upload date, duration, and sort order.
youtube_get_transcript	Get timestamped transcript text from a video. Supports format options, time range filtering, and segment limits.
youtube_get_video_info	Get video metadata with brief/standard/full detail levels (title, description, tags, chapters, likes).
youtube_get_channel_info	Get channel metadata — name, handle, description, subscriber count, country.
youtube_get_channel_videos	List a channel's uploads. Sort by newest, popular, or oldest. Accepts @handle, URL, or channel ID.
youtube_get_playlist	Get a playlist's metadata and video list with positions.

Skills

Skill	Description
/youtube:setup	Guided setup wizard — configure search mode (anonymous/personalized) and plugin settings.
/youtube	YouTube research guide — tool usage, parameter reference, and transcript analysis workflows.

Agents

Agent	Description
video-watcher	Watches a video and reports back — key points, takeaways, notable quotes, and topic tags. Accepts custom analysis instructions.

Installation

Recommended: Claude Code

/plugin marketplace add JCodesMore/jcodesmore-plugins
/plugin install youtube@jcodesmore-plugins

Full plugin experience out of the box — MCP tools, skills, and agents.

Platform Support

Platform	MCP Tools	Plugin (Skills/Agents)	Setup
Claude Code	✓	✓	Setup Guide
Cursor	✓	✓	Setup Guide
Codex	✓	—	Setup Guide
OpenCode	✓	✓ (via plugin)	Setup Guide
Gemini CLI	✓	—	Setup Guide

Any MCP Client (npx)

Works with Claude Desktop, Cursor, Windsurf, and any other MCP-compatible client:

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@jcodesmore/youtube-mcp"]
    }
  }
}

Manual Install (from source)

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

Configure your MCP client to run the server:

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

Verify

Start a new session and try any YouTube tool — search for a video or pull a transcript. All youtube_* tools should be available.

Authentication

The plugin works in two modes:

Anonymous (default)

Works out of the box with no setup. YouTube search results and metadata are publicly available. Some features like personalized recommendations are not available.

Personalized (optional)

Uses your YouTube login cookies to access personalized results. To set up:

1. Run the setup skill inside Claude Code: /youtube:setup
2. Follow the guided walkthrough to extract cookies from Chrome

The setup creates a dedicated Chrome profile — your main browser profile is never accessed. Cookies are stored locally in the plugin data directory (CLAUDE_PLUGIN_DATA) and never transmitted anywhere. If CLAUDE_PLUGIN_DATA is not set, the script falls back to .cookies.json in the current directory.

Configuration

Use the setup skill (/youtube:setup) to configure defaults for search limits, transcript language, channel video sorting, and more. Or use the CLI directly from the plugin root:

# View current settings
node scripts/config.mjs --show

# Change a setting
node scripts/config.mjs --set search.defaultLimit 20

# Reset to defaults
node scripts/config.mjs --reset

Project Structure

youtube-mcp/
├── src/                        # TypeScript MCP server (portable)
│   ├── index.ts                # Server setup and tool registration
│   ├── config.ts               # Configuration defaults and types
│   ├── lib/                    # Core libraries
│   │   ├── innertube.ts        # YouTube API wrapper (youtubei.js)
│   │   ├── transcript.ts       # Transcript fetching and cleanup
│   │   ├── cookies.ts          # Cookie loading, validation, persistence
│   │   └── user-config.ts      # User configuration management
│   └── tools/                  # MCP tool handlers
│       ├── search.ts           # youtube_search
│       ├── transcript.ts       # youtube_get_transcript
│       ├── video-info.ts       # youtube_get_video_info
│       ├── channel-info.ts     # youtube_get_channel_info
│       ├── channel-videos.ts   # youtube_get_channel_videos
│       └── playlist.ts         # youtube_get_playlist
├── skills/                     # Skills (shared across platforms)
│   ├── setup/SKILL.md          # Setup wizard
│   └── youtube/SKILL.md        # Research guide
├── agents/                     # Agents (Claude Code + Cursor)
│   └── video-watcher.md
├── scripts/                    # Utility scripts
│   ├── config.mjs              # Configuration CLI
│   └── extract-cookies.mjs     # Chrome cookie extraction
├── docs/                       # Per-platform setup guides
│   ├── README.claude-code.md
│   ├── README.cursor.md
│   ├── README.codex.md
│   ├── README.opencode.md
│   └── README.gemini-cli.md
├── .claude-plugin/             # Claude Code plugin manifest
├── .cursor-plugin/             # Cursor plugin manifest
├── .opencode/plugins/          # OpenCode plugin loader
├── gemini-extension.json       # Gemini CLI extension manifest
└── GEMINI.md                   # Gemini CLI context file

Tech Stack

• MCP SDK — Model Context Protocol server implementation
• youtubei.js — YouTube InnerTube API client
• youtube-transcript-plus — Transcript extraction
• Zod — Runtime schema validation
• puppeteer-core — Chrome automation for cookie extraction (optional)

Disclaimer

This plugin uses youtubei.js, an unofficial YouTube API client. It is not affiliated with, endorsed by, or associated with YouTube or Google. YouTube may change their internal APIs at any time, which could break functionality. Use at your own discretion.

License

Apache 2.0