Youtube MCP Server

YouTube MCP 服务

最后更新：2025-07-05

一个使用 YouTube Data API 实现的模型上下文协议（MCP）服务。它允许 AI 大模型通过标准化接口与 YouTube 内容交互。

✅ 支持 YouTube 字幕稿：此服务使用 youtube-transcript-api Python 包，提供完整的字幕稿/字幕功能。只需安装 Python 依赖项，并可选择配置 Python 路径，即可无缝获取有可用字幕的视频字幕稿。

目录

• 主要功能
• OAuth 身份验证（私人播放列表）
• 可用工具
• 快速开始
• 先决条件
  • 1. Python 设置（字幕稿功能所必需）
  • 2. YouTube Data API 设置
  • 3. OAuth 设置（私人播放列表，可选）
• 环境配置
• 故障排除
• 开发
• 系统要求
• 安全注意事项
• 致谢
• 许可证

主要功能

视频信息

• 获取详细的视频信息（标题、说明、时长、统计数据）
• 按关键词搜索视频
• 根据指定视频获取相关视频
• 计算并分析视频互动率

✅ 字幕稿/字幕管理（功能完备）

• 使用强大的 youtube-transcript-api Python 包获取视频字幕稿
• 支持多种语言，可自动检测语言并使用回退选项
• 带时间戳的字幕，便于精确引用和分析内容
• 轻松设置——只需安装 Python 依赖项，并可选择设置 Python 路径
• 适用于任何有可用字幕/字幕稿的视频，运行可靠

频道分析

• 查看详细的频道统计数据（订阅者数、观看次数、视频数量）
• 获取频道中表现最佳的视频
• 分析频道增长和互动指标

播放列表管理

• 获取详细的播放列表信息
• 获取播放列表中的所有视频
• 按关键词搜索公开播放列表
• 获取指定频道的所有公开播放列表

趋势分析

• 按地区和类别查看热门视频
• 比较多个视频的表现指标
• 发现特定类别中的热门内容

OAuth 身份验证（私人播放列表）

注意：只有在需要访问自己的私人 YouTube 播放列表时才需要 OAuth。访问公开内容无需身份验证。

身份验证步骤

1. 确保已配置 OAuth（请参阅上文的先决条件部分）

2. 通过 Google 进行身份验证：

   对于 npx 用户：

   npx yt-mcp-auth auth
   

   对于本地开发：

   npm run auth
   

3. 处理“Google 尚未验证此应用”警告：

   • 点击“Advanced”（高级）
   • 点击“Go to [your app name] (unsafe)”（前往 [your app name]（不安全））
   • 由于 OAuth 应用是你自己创建的，因此这样做是安全的

4. 完成 OAuth 流程：

   • 授予所请求的权限
   • 身份验证完成后，你会看到成功消息

5. 验证身份验证状态：

   对于 npx 用户：

   npx yt-mcp-auth status
   

   对于本地开发：

   npm run auth:status
   

管理身份验证

查看状态：

# npx users
npx yt-mcp-auth status

# Local development  
npm run auth:status

撤销身份验证：

# npx users
npx yt-mcp-auth revoke

# Local development
npm run auth:revoke

完成身份验证后，你可以使用 getMyPlaylists 工具访问自己的私人播放列表。

可用工具

该服务提供以下 MCP 工具：

工具名称	描述	必需参数
getVideoDetails	获取多个 YouTube 视频的详细信息，包括元数据、统计数据和内容详情	videoIds（数组）
searchVideos	根据查询字符串搜索视频	query、maxResults（可选）
getTranscripts	获取多个视频的字幕稿	videoIds（数组）、lang（可选）
getRelatedVideos	根据 YouTube 的推荐算法获取与特定视频相关的视频	videoId、maxResults（可选）
getChannelStatistics	获取多个频道的详细指标，包括订阅者数量、观看次数和视频数量	channelIds（数组）
getChannelTopVideos	获取特定频道观看次数最多的视频	channelId、maxResults（可选）
getVideoEngagementRatio	计算多个视频的互动指标（观看次数、点赞数、评论数和互动率）	videoIds（数组）
getTrendingVideos	按地区和类别获取当前热门视频	regionCode（可选）、categoryId（可选）、maxResults（可选）
compareVideos	比较多个视频的统计数据	videoIds（数组）
getPlaylistDetails	获取特定 YouTube 播放列表的详细信息	playlistId
getPlaylistVideos	获取特定播放列表中的所有视频	playlistId、maxResults（可选）
searchPublicPlaylists	根据查询字符串搜索公开播放列表	query、maxResults（可选）、channelId（可选）
getChannelPlaylists	获取特定频道的所有公开播放列表	channelId、maxResults（可选）
getMyPlaylists	获取你自己的播放列表（包括私密播放列表）	maxResults（可选）
checkOAuthStatus	检查 OAuth 身份验证是否已启用	无

快速开始

选项 1：使用 npx（推荐）

无需安装！可直接与 Claude Desktop 搭配使用：

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "yt-mcp"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_API_KEY_HERE",
        "YOUTUBE_TRANSCRIPT_LANG": "en"
      }
    }
  }
}

选项 2：本地开发

git clone https://github.com/space-cadet/yt-mcp.git
cd yt-mcp
npm install
npm run build

前置条件

1. 🐍 Python 设置（字幕稿功能必需）

✅ YouTube 字幕稿功能已全面支持并可正常使用！

字幕稿功能使用 Python 包 youtube-transcript-api，可靠地获取任何提供字幕的视频的字幕稿。

📋 设置步骤：

1. 安装 Python（如果尚未安装）：

   • 需要 Python 3.7 或更高版本
   • 从 python.org 下载，或使用系统的软件包管理器安装
   • 验证安装：python --version 或 python3 --version

2. 安装 Python 字幕稿包：

   pip install youtube-transcript-api
   

   或者，如果你使用 pip3：

   pip3 install youtube-transcript-api
   

3. 配置 Python 路径（如有需要）：

   • 大多数用户无需执行此步骤——服务会自动查找 python3
   • 仅当你使用 conda、虚拟环境或自定义 Python 安装时才需要此步骤
   • 在环境中设置 PYTHON_PATH，使其指向 Python 可执行文件
   • 示例：
     • /Users/username/miniconda3/bin/python
     • /opt/homebrew/bin/python3
     • C:\Python39\python.exe (Windows)

🎯 就是这样！ 安装 Python 和该包后，任何提供字幕的视频都可以立即使用字幕稿功能。

2. YouTube Data API 设置

Google Cloud Console 分步设置：

1. 创建／选择项目：

   • 前往 Google Cloud Console
   • 点击“Select a project” → “New Project”
   • 为项目命名（例如，“YouTube MCP Server”）
   • 点击“Create”

2. 启用 YouTube Data API v3：

   • 在侧边栏中，前往“APIs & Services” → “Library”
   • 搜索“YouTube Data API v3”
   • 点击该项，然后点击“Enable”

3. 创建 API 密钥：

   • 前往“APIs & Services” → “Credentials”
   • 点击“Create Credentials” → “API Key”
   • 复制生成的 API 密钥
   • （可选）点击“Restrict Key”，将其限制为仅用于 YouTube Data API v3

3. OAuth 设置（用于私密播放列表——可选）

仅当你想访问私密播放列表时才需要：

1. 创建 OAuth 2.0 凭据：
   • 前往“APIs & Services” → “Credentials”
   • 点击“Create Credentials” → “OAuth 2.0 Client ID”
   • 如果系统提示，请先配置 OAuth 同意屏幕：
     • 选择“External”用户类型
     • 填写应用名称、用户支持邮箱和开发者联系信息
     • 将你的邮箱添加为测试用户
   • 选择“Web application”作为应用类型
   • 添加授权重定向 URI：http://localhost:3000/oauth2callback
   • 复制 Client ID 和 Client Secret

环境配置

对于 npx 用户

将环境变量直接添加到 Claude Desktop MCP 配置中：

基本配置（公开内容 + 转录文本）：

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "yt-mcp"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_API_KEY_HERE",
        "YOUTUBE_TRANSCRIPT_LANG": "en"
      }
    }
  }
}

注意：此配置包含完整的转录文本功能！只需确保已安装 Python 和 youtube-transcript-api。

带自定义 Python 路径的配置（适用于 conda／虚拟环境）：

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "yt-mcp"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_API_KEY_HERE",
        "YOUTUBE_TRANSCRIPT_LANG": "en",
        "PYTHON_PATH": "/path/to/your/python"
      }
    }
  }
}

注意：大多数用户无需设置 PYTHON_PATH——只有在使用 conda、虚拟环境或自定义 Python 安装时才需要设置。

完整配置（包含 OAuth 和自定义 Python 路径）：

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "yt-mcp"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_API_KEY_HERE",
        "YOUTUBE_TRANSCRIPT_LANG": "en",
        "PYTHON_PATH": "/path/to/your/python",
        "GOOGLE_OAUTH_CLIENT_ID": "YOUR_OAUTH_CLIENT_ID",
        "GOOGLE_OAUTH_CLIENT_SECRET": "YOUR_OAUTH_CLIENT_SECRET",
        "OAUTH_REDIRECT_URI": "http://localhost:3000/oauth2callback"
      }
    }
  }
}

对于本地开发

在项目根目录中创建 .env 文件：

# Required
YOUTUBE_API_KEY=your_youtube_api_key_here

# Optional
YOUTUBE_TRANSCRIPT_LANG=en
PYTHON_PATH=/path/to/your/python

# OAuth (for private playlists)
GOOGLE_OAUTH_CLIENT_ID=your_oauth_client_id
GOOGLE_OAUTH_CLIENT_SECRET=your_oauth_client_secret
OAUTH_REDIRECT_URI=http://localhost:3000/oauth2callback

本地开发 MCP 配置：

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

故障排除

常见问题

“Error: YOUTUBE_API_KEY environment variable is not set”

• 确保已将 YouTube API 密钥添加到 MCP 配置中
• 确认 API 密钥有效，并已启用 YouTube Data API v3

OAuth 期间出现“Google hasn't verified this app”警告

• 个人 OAuth 应用出现此提示属于正常情况
• 点击“Advanced” → “Go to [app name] (unsafe)”以继续
• 由于 OAuth 凭据由你自己创建，因此可以放心操作

“OAuth authentication required”错误

• 运行身份验证命令：npx yt-mcp-auth auth（本地运行时使用 npm run auth）
• 确保已在环境中正确配置 OAuth 凭据

撤销身份验证时出现“invalid_token”错误

• 如果令牌已过期，可能会出现此情况
• 该命令仍会清理本地身份验证状态
• 出现此错误后，你仍可安全地重新进行身份验证

🐍 字幕稿功能故障排除

✅ 好消息：字幕稿功能运行正常，并经过了充分测试！大多数问题都只是简单的设置问题。

• “ModuleNotFoundError: No module named 'youtube_transcript_api'”：

  • 解决方案：安装 Python 程序包：pip install youtube-transcript-api
  • 如果使用 conda/虚拟环境，请确保程序包已安装在相应环境中
  • 使用以下命令确认：python -c "import youtube_transcript_api; print('Package installed successfully!')"

• **“Failed to start Python process”**或找不到 Python：

  • 解决方案：将 PYTHON_PATH 环境变量设为 Python 可执行文件的路径
  • 查找 Python 路径：which python3（macOS/Linux）或 where python（Windows）
  • 添加到 MCP 配置中："PYTHON_PATH": "/path/to/your/python"
  • 示例：
    • "/usr/bin/python3"（系统 Python）
    • "/Users/username/miniconda3/bin/python"（conda）
    • "C:\\Python39\\python.exe"（Windows）

• 字幕稿结果为空：

  • **这是正常的！**有些视频没有可用的字幕稿
  • 尝试热门视频（例如 TED 演讲、教育内容），这类视频通常带有字幕
  • 使用已知可正常运行的视频进行测试，以确认功能正常
  • 对于没有字幕的视频，字幕稿 API 会返回空结果

• 字幕稿语言问题：

  • 将 YOUTUBE_TRANSCRIPT_LANG 设为首选语言（例如，“en”“es”“fr”）
  • 如果没有首选语言，API 会自动回退到可用语言

MCP 服务无响应

• 确认 Node.js 版本为 18.0.0 或更高
• 检查 YouTube API 密钥是否有效
• 对于本地开发，请确保已运行 npm run build

获取帮助

如果遇到问题：

1. 查看上方的故障排除部分
2. 检查 API 密钥和 OAuth 设置
3. 在 GitHub 上提交 issue

开发

本地开发设置

# Clone and setup
git clone https://github.com/space-cadet/yt-mcp.git
cd yt-mcp
npm install

# Create .env file with your credentials
cp .env.example .env
# Edit .env with your API keys

# Development commands
npm run dev      # Run in development mode with auto-reload
npm run build    # Build TypeScript to JavaScript  
npm run start    # Run built version
npm test         # Run tests
npm run lint     # Lint code

项目结构

src/
├── index.ts              # Main MCP server
├── auth-cli.ts           # OAuth authentication CLI
├── functions/
│   ├── videos.ts         # Video-related API functions
│   └── playlists.ts      # Playlist-related API functions
└── utils/
    ├── oauth.ts          # OAuth token management
    ├── oauth-routes.ts   # OAuth callback server
    └── cli-auth.ts       # CLI authentication flow

系统要求

• Node.js 18.0.0 或更高
• 访问 YouTube API 所需的互联网连接
• OAuth 回调所需的可用 3000 端口（使用 OAuth 时）

安全注意事项

• 切勿将 API 密钥或 OAuth 密钥提交到版本控制中
• 所有敏感配置都使用环境变量
• 为 Google Cloud API 密钥设置使用配额，以防止滥用
• OAuth 令牌存储在本地的 tokens.json 中，请妥善保管此文件
• 不再需要时，请考虑撤销 OAuth 访问权限

致谢

本项目由 icraft2170 基于 youtube-data-mcp-server 分叉而来。特别感谢原作者为这个 YouTube MCP 服务实现奠定了基础。

许可证

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