YouTube MCP Server for Claude Code: Setup & Config

What you can do with YouTube in Claude Code

A research-focused YouTube interface with transcripts, filtered creator discovery, and quota fallback.

• Search videos within publication dates and channel constraints.
• Inspect channel uploads and playlist contents.

Before you start: YouTube in Claude Code

• Node.js and npx
• At least one YouTube Data API key
• An MCP-compatible client

Uses the README's npx configuration, not the different package in the structured config hint. YOUTUBE_API_KEY2 and YOUTUBE_API_KEY3 are optional fallback keys. YOUTUBE_TRANSCRIPT_LANG optionally changes the default transcript language. Docker defaults to HTTP at http://localhost:8088/mcp.

YouTube Claude Code configuration

1. Choose Claude Code configuration scope

   For YouTube MCP Server, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add YouTube MCP Server to Claude Code

   Use the youtube-mcp-server entry below in mcpServers. Keep YouTube MCP Server's documented stdio connection fields and your other Claude Code entries.

3. Check YouTube MCP Server in Claude Code

   YouTube MCP Server: Inspect claude mcp list and /mcp status.

{
  "mcpServers": {
    "youtube-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "zubeid-youtube-mcp-server"
      ],
      "env": {
        "YOUTUBE_API_KEY": "<YouTube Data API key>"
      }
    }
  }
}

claude mcp add-json --scope project 'youtube-mcp-server' '{"type":"stdio","command":"npx","args":["-y","zubeid-youtube-mcp-server"],"env":{"YOUTUBE_API_KEY":"<YouTube Data API key>"}}'

YouTube tools available to Claude Code

YouTube's stored tool list documents 10 tools; compare it with Claude Code's connected tool list, because the stored list is not a live check.

videos_getVideo

For YouTube's videos_getVideo, review the permission request and arguments in Claude Code before approval.

Retrieve video details, optionally selecting resource parts.

videos_searchVideos

For YouTube's videos_searchVideos, review the permission request and arguments in Claude Code before approval.

Search videos using date, channel, subscriber, activity, and ordering filters.

transcripts_getTranscript

For YouTube's transcripts_getTranscript, review the permission request and arguments in Claude Code before approval.

Retrieve a video's transcript in a requested or configured language.

channels_getChannel

For YouTube's channels_getChannel, review the permission request and arguments in Claude Code before approval.

channels_getChannels

For YouTube's channels_getChannels, review the permission request and arguments in Claude Code before approval.

channels_searchChannels

For YouTube's channels_searchChannels, review the permission request and arguments in Claude Code before approval.

channels_findCreators

For YouTube's channels_findCreators, review the permission request and arguments in Claude Code before approval.

channels_listVideos

For YouTube's channels_listVideos, review the permission request and arguments in Claude Code before approval.

List videos belonging to a specified channel.

playlists_getPlaylist

For YouTube's playlists_getPlaylist, review the permission request and arguments in Claude Code before approval.

Inspect details for a selected playlist.

playlists_getPlaylistItems

For YouTube's playlists_getPlaylistItems, review the permission request and arguments in Claude Code before approval.

YouTube: full stored tool descriptions

Troubleshooting YouTube in Claude Code

• If YouTube MCP Server fails to start, check npx zubeid-youtube-mcp-server (Node.js/npm), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• YouTube MCP Server: check YOUTUBE_API_KEY; keep credentials out of shared .mcp.json.
• YouTube MCP Server uses stdio here: Claude Code must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: At least one YouTube Data API key is required.
• Known limitation: Creator-only filtering uses heuristics rather than a guaranteed classification.
• Known limitation: The Docker build can include credentials from its copied environment file.
• General Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions