YouTube MCP Server

YouTube MCP Server

一个用于 YouTube 的模型上下文协议（MCP）服务实现，可通过标准化接口让 AI 大模型与 YouTube 内容交互。

网站： zubeidhendricks.github.io/youtube-mcp-server

可用工具

该服务目前提供 10 个 MCP 工具。

工具	描述	必需参数	可选参数
videos_getVideo	获取 YouTube 视频的详细信息	videoId	parts
videos_searchVideos	搜索 YouTube 上的视频	query	maxResults、order、publishedAfter、publishedBefore、channelId、uniqueChannels、channelMinSubscribers、channelMaxSubscribers、channelLastUploadAfter、channelLastUploadBefore、creatorOnly、sortBy
transcripts_getTranscript	获取 YouTube 视频的文字稿	videoId	language
channels_getChannel	获取 YouTube 频道的信息	channelId	无
channels_getChannels	获取多个 YouTube 频道的信息	channelIds	parts、includeLatestUpload
channels_searchChannels	按用户名、名称或查询词搜索 YouTube 频道	query	maxResults、order、channelType、minSubscribers、maxSubscribers、lastUploadAfter、lastUploadBefore、creatorOnly、sortBy
channels_findCreators	根据视频提及查找创作者频道，并按频道规模和活跃度筛选	query	maxResults、order、videoPublishedAfter、videoPublishedBefore、channelMinSubscribers、channelMaxSubscribers、channelLastUploadAfter、channelLastUploadBefore、creatorOnly、sortBy、sampleVideosPerChannel
channels_listVideos	获取特定频道的视频	channelId	maxResults
playlists_getPlaylist	获取 YouTube 播放列表的信息	playlistId	无
playlists_getPlaylistItems	获取 YouTube 播放列表中的视频	playlistId	maxResults

工具参数

videos_getVideo

• videoId（string）：YouTube 视频 ID。
• parts（string[]，可选）：要获取的特定视频资源部分。

videos_searchVideos

• query（string）：搜索查询词。
• maxResults（number，可选）：返回结果的最大数量。
• order（string，可选）：结果排序方式，例如 relevance 或 date。
• publishedAfter（string，可选）：仅包含在此 ISO 8601 日期之后发布的视频。
• publishedBefore（string，可选）：仅包含在此 ISO 8601 日期之前发布的视频。
• channelId（string，可选）：将结果限定为特定频道。
• uniqueChannels（boolean，可选）：每个不同频道仅返回一个视频。
• channelMinSubscribers / channelMaxSubscribers（number，可选）：按匹配视频所属频道的订阅者数量范围筛选。
• channelLastUploadAfter / channelLastUploadBefore（string，可选）：按匹配视频所属频道的最近上传时间筛选。
• creatorOnly（boolean，可选）：将结果限定为启发式分类为创作者的频道。
• sortBy（string，可选）：支持 relevance、subscribers_asc、subscribers_desc、indie_priority 和 recent_activity。

transcripts_getTranscript

• videoId（string）：YouTube 视频 ID。
• language（string，可选）：文字稿语言代码。未指定时使用 YOUTUBE_TRANSCRIPT_LANG，否则默认为 en。

channels_getChannel

• channelId（string）：YouTube 频道 ID。

响应现在包含：

• latestVideoPublishedAt
• normalizedMetadata
  • 包含 country、defaultLanguage、joinedAt、customUrl、emailsFound、contactLinks，以及用于区分创作者与品牌的启发式字段

channels_getChannels

• channelIds（string[]）：YouTube 频道 ID 列表。
• includeLatestUpload（boolean，可选）：是否包含 latestVideoPublishedAt。默认为 true。

channels_searchChannels

• query（string）：频道搜索查询或账号名。
• maxResults（number，可选）：返回的频道数量上限。
• order（string，可选）：结果排序方式，例如 relevance。
• channelType（string，可选）：将搜索范围限定为某种频道类型。
• minSubscribers / maxSubscribers（number，可选）：按订阅者数量范围筛选频道。
• lastUploadAfter / lastUploadBefore（string，可选）：按最新上传活动筛选频道。
• creatorOnly（boolean，可选）：将结果限定为通过启发式方法归类为创作者的频道。
• sortBy（string，可选）：支持 relevance、subscribers_asc、subscribers_desc、indie_priority 和 recent_activity。

channels_findCreators

• query（string）：用于从匹配的视频中发现频道的主题、游戏或提及内容。
• videoPublishedAfter / videoPublishedBefore（string，可选）：匹配视频的时效筛选条件。
• channelMinSubscribers / channelMaxSubscribers（number，可选）：返回频道的订阅者数量范围筛选条件。
• channelLastUploadAfter / channelLastUploadBefore（string，可选）：返回频道的最新上传活动筛选条件。
• creatorOnly（boolean，可选）：将结果限定为通过启发式方法归类为创作者的频道。
• sortBy（string，可选）：支持 relevance、subscribers_asc、subscribers_desc、indie_priority 和 recent_activity。
• sampleVideosPerChannel（number，可选）：每个返回频道包含的匹配视频数量。

channels_listVideos

• channelId（string）：YouTube 频道 ID。
• maxResults（number，可选）：返回的视频数量上限。

playlists_getPlaylist

• playlistId（string）：YouTube 播放列表 ID。

playlists_getPlaylistItems

• playlistId（string）：YouTube 播放列表 ID。
• maxResults（number，可选）：返回的播放列表项数量上限。

安装

Claude Desktop 快速设置

1. 安装软件包：

npm install -g zubeid-youtube-mcp-server

2. 添加到 Claude Desktop 配置中（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "zubeid-youtube-mcp-server": {
      "command": "zubeid-youtube-mcp-server",
      "env": {
        "YOUTUBE_API_KEY": "your_primary_youtube_api_key",
        "YOUTUBE_API_KEY2": "your_secondary_youtube_api_key",
        "YOUTUBE_API_KEY3": "your_tertiary_youtube_api_key"
      }
    }
  }
}

替代方案：使用 NPX（无需安装）

将以下内容添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "zubeid-youtube-mcp-server"],
      "env": {
        "YOUTUBE_API_KEY": "your_primary_youtube_api_key",
        "YOUTUBE_API_KEY2": "your_secondary_youtube_api_key",
        "YOUTUBE_API_KEY3": "your_tertiary_youtube_api_key"
      }
    }
  }
}

通过 Smithery 安装

如需通过 Smithery 自动为 Claude Desktop 安装 YouTube MCP Server：

npx -y @smithery/cli install @ZubeidHendricks/youtube --client claude

配置

设置以下环境变量：

• YOUTUBE_API_KEY：主要的 YouTube Data API 密钥
• YOUTUBE_API_KEY2：备用 API 密钥
• YOUTUBE_API_KEY3：第三个备用 API 密钥
• YOUTUBE_TRANSCRIPT_LANG：字幕的默认语言（可选，默认为 'en'）

必须至少设置 YOUTUBE_API_KEY、YOUTUBE_API_KEY2 或 YOUTUBE_API_KEY3 中的一个。当请求因某个密钥的配额耗尽而失败时，服务会使用下一个已配置的密钥重试相同请求。

在 VS Code 中使用

如需一键安装，请点击下方的其中一个安装按钮：

手动安装

如果你更倾向于手动安装，请先查看本节顶部的安装按钮。否则，请按以下步骤操作：

将以下 JSON 代码块添加到 VS Code 的用户设置（JSON）文件中。你可以按 Ctrl + Shift + P，然后输入 Preferences: Open User Settings (JSON) 来打开该文件。

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "YouTube API Key",
        "password": true
      }
    ],
    "servers": {
      "youtube": {
        "command": "npx",
        "args": ["-y", "zubeid-youtube-mcp-server"],
        "env": {
          "YOUTUBE_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

你也可以选择将其添加到工作区中名为 .vscode/mcp.json 的文件：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "YouTube API Key",
      "password": true
    }
  ],
  "servers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "zubeid-youtube-mcp-server"],
      "env": {
        "YOUTUBE_API_KEY": "${input:apiKey}"
      }
    }
  }
}

开发

# Install dependencies
npm install

# Build
npm run build

# Start the server (requires at least one configured YouTube API key)
npm start

# Development mode with auto-rebuild
npm run dev

Docker

随附的 Docker 镜像默认通过 HTTP 启动服务。

• 默认传输方式：http
• 默认端点：http://localhost:8088/mcp
• 就绪端点：http://localhost:8088/ready
• 默认模式：无状态

Docker 构建会将 .env 复制到运行时镜像中，服务会在启动时自动加载该文件。这意味着只要 .env 在 docker build 时存在，容器运行时就无需通过 docker run 传入 API 凭据。

docker build -t youtube-mcp-server .
docker run --rm -p 8088:8088 youtube-mcp-server

容器默认配置如下：

MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8088
MCP_STATELESS=true

贡献

有关如何为此代码库做贡献的信息，请参阅 CONTRIBUTING.md。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。