内容
# YouTube 播放列表生成器 MCP 服务器
一个 Model Context Protocol (MCP) 服务器，允许 AI 应用程序搜索 YouTube 音乐视频并使用官方 YouTube Data API v3 管理播放列表。
## 功能
- **搜索音乐视频**：在 YouTube 上查找音乐视频，支持自定义搜索参数
- **获取视频详情**：检索特定视频的详细信息
- **获取播放列表项目**：列出公共播放列表中的视频
- **播放列表管理**：完整的播放列表管理功能，包括创建、编辑和管理播放列表（需要 OAuth 设置）
## 设置
### 前置条件
- Node.js 18 或更高版本
- 启用了 YouTube Data API v3 的 Google Cloud 项目
- YouTube Data API 密钥
- OAuth 2.0 客户端凭证（可选，播放列表管理功能需要）
### 安装
1. 克隆此仓库：
```bash
git clone https://github.com/danisss9/yt-playlist-generator-mcp-server
```
2. 安装依赖：
```bash
npm install
```
3. 获取 YouTube Data API 密钥：
- 访问 [Google Cloud 控制台](https://console.cloud.google.com/)
- 创建新项目或选择现有项目
- 启用 YouTube Data API v3
- 创建凭证（API 密钥）
- 复制 API 密钥
4. 设置环境变量：
```bash
# 创建 .env 文件
echo "YOUTUBE_API_KEY=your_api_key_here" > .env
echo "YOUTUBE_CLIENT_ID=your_client_id_here" >> .env
echo "YOUTUBE_CLIENT_SECRET=your_client_secret_here" >> .env
```
5. 编译 TypeScript 代码：
```bash
npm run build
```
### 运行服务器
开发模式下自动重建：
```bash
npm run dev
```
生产环境：
```bash
npm start
```
### 与 MCP 客户端一起使用
此服务器使用 stdio 传输，因此可以与任何支持 stdio 的 MCP 客户端一起使用。
#### Claude Desktop 配置
将以下内容添加到您的 Claude Desktop 配置文件中：
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"youtube-playlist-generator": {
"command": "node",
"args": ["/absolute/path/to/yt-playlist-generator/build/index.js"],
"env": {
"YOUTUBE_API_KEY": "your_youtube_api_key_here",
"YOUTUBE_CLIENT_ID": "your_client_id_here",
"YOUTUBE_CLIENT_SECRET": "your_client_secret_here"
}
}
}
}
```
#### Visual Studio Code 与 GitHub Copilot 配置
要在 Visual Studio Code 中与 GitHub Copilot 一起使用此 MCP 服务器，您需要在 VS Code 设置中进行配置：
1. **打开 VS Code 设置**：按 `Ctrl+,` （Windows/Linux）或 `Cmd+,` （macOS）
2. **搜索 MCP**：在搜索栏中输入 "mcp"
3. **添加 MCP 服务器配置**：将以下内容添加到您的 VS Code 设置 JSON 中：
```json
{
"github.copilot.chat.mcp.servers": {
"youtube-playlist-generator": {
"command": "node",
"args": ["/absolute/path/to/yt-playlist-generator/build/index.js"],
"env": {
"YOUTUBE_API_KEY": "your_youtube_api_key_here",
"YOUTUBE_CLIENT_ID": "your_client_id_here",
"YOUTUBE_CLIENT_SECRET": "your_client_secret_here"
}
}
}
}
```
**替代：使用设置 UI**
1. 访问 **文件 > 首选项 > 设置** （或使用 `Ctrl+,`）
2. 搜索 "GitHub Copilot MCP"
3. 点击 "在 settings.json 中编辑" 以获取 "Github › Copilot › Chat: Mcp Servers"
4. 添加服务器配置，如上所示
**环境变量设置**
出于安全考虑，您也可以在系统范围内设置环境变量，而不是在配置文件中：
**Windows (PowerShell)**：
```powershell
[Environment]::SetEnvironmentVariable("YOUTUBE_API_KEY", "your_api_key_here", "User")
[Environment]::SetEnvironmentVariable("YOUTUBE_CLIENT_ID", "your_client_id_here", "User")
[Environment]::SetEnvironmentVariable("YOUTUBE_CLIENT_SECRET", "your_client_secret_here", "User")
```
**Windows (命令提示符)**：
```cmd
setx YOUTUBE_API_KEY "your_api_key_here"
setx YOUTUBE_CLIENT_ID "your_client_id_here"
setx YOUTUBE_CLIENT_SECRET "your_client_secret_here"
```
**macOS/Linux**：
```bash
export YOUTUBE_API_KEY="your_api_key_here"
export YOUTUBE_CLIENT_ID="your_client_id_here"
export YOUTUBE_CLIENT_SECRET="your_client_secret_here"
# 添加到 ~/.bashrc、~/.zshrc 或 ~/.profile 以保持持久
echo 'export YOUTUBE_API_KEY="your_api_key_here"' >> ~/.bashrc
echo 'export YOUTUBE_CLIENT_ID="your_client_id_here"' >> ~/.bashrc
echo 'export YOUTUBE_CLIENT_SECRET="your_client_secret_here"' >> ~/.bashrc
```
然后从 VS Code 配置中删除 `env` 部分：
```json
{
"github.copilot.chat.mcp.servers": {
"youtube-playlist-generator": {
"command": "node",
"args": ["/absolute/path/to/yt-playlist-generator/build/index.js"]
}
}
}
```
**在 VS Code 中使用**
配置完成后，您可以通过 GitHub Copilot Chat 使用 MCP 服务器：
1. 打开 Copilot Chat（`Ctrl+Alt+I` 或点击聊天图标）
2. 使用自然语言与 YouTube 交互：
- "搜索关于爵士乐的音乐视频"
- "创建一个名为 '我的最爱' 的新播放列表"
- "将此视频添加到我的播放列表中"
- "显示此 YouTube 视频的详细信息"
## 可用工具
### 只读工具（API 密钥身份验证）
#### 搜索音乐视频
在 YouTube 上搜索符合指定条件的音乐视频。
**参数：**
- `query` （字符串）：音乐视频的搜索查询
- `maxResults` （数字，1-50，默认为 10）：最大结果数
- `order` （枚举）：排序 - "relevance", "date", "rating", "viewCount", "title"
#### 获取视频详情
获取特定 YouTube 视频的详细信息。
**参数：**
- `videoId` （字符串）：YouTube 视频 ID
#### 获取播放列表项目
从公共 YouTube 播放列表中检索视频。
**参数：**
- `playlistId` （字符串）：YouTube 播放列表 ID
- `maxResults` （数字，1-50，默认为 25）：最大项目数
### 需要 OAuth 的工具（播放列表管理）
#### YouTube 身份验证
使用 YouTube OAuth 启用播放列表管理功能。
**参数：**
- `getAuthUrl` （布尔值，默认为 false）：设置为 true 以获取授权 URL
- `authCode` （字符串，可选）：OAuth 流中的授权代码
#### 获取身份验证状态
检查当前的 OAuth 身份验证状态。
**参数：** 无
#### 创建播放列表
创建新的 YouTube 播放列表（需要 OAuth 身份验证）。
**参数：**
- `title` （字符串）：播放列表标题
- `description` （字符串，可选）：播放列表描述
- `privacy` （枚举）："private", "public", 或 "unlisted"
#### 编辑播放列表
编辑现有的播放列表信息（需要 OAuth 身份验证）。
**参数：**
- `playlistId` （字符串）：要编辑的播放列表 ID
- `title` （字符串，可选）：播放列表的新标题
- `description` （字符串，可选）：播放列表的新描述
- `privacy` （枚举，可选）：新的隐私设置 - "private", "public", 或 "unlisted"
**注意：** 必须提供至少一个字段（标题、描述或隐私）才能更新。
#### 添加到播放列表
将视频添加到现有的播放列表（需要 OAuth 身份验证）。
**参数：**
- `playlistId` （字符串）：目标播放列表 ID
- `videoId` （字符串）：要添加的视频 ID
#### 列出播放列表
列出用户的播放列表（需要 OAuth 身份验证）。
**参数：**
- `maxResults` （数字，1-50，默认为 25）：最大播放列表数
- `mine` （布尔值，默认为 true）：列出已身份验证用户的播放列表
#### 从播放列表中删除
从播放列表中删除视频（需要 OAuth 身份验证）。
**参数：**
- `playlistItemId` （字符串）：要删除的播放列表项目 ID（从 get_playlist_items 获取）
## OAuth 身份验证设置
要启用完整的播放列表管理功能，您需要设置 OAuth 2.0：
### 1. Google Cloud 控制台设置
1. 访问 [Google Cloud 控制台](https://console.cloud.google.com/)
2. 创建新项目或选择现有项目
3. 启用 YouTube Data API v3
4. 进入 "凭证" → "创建凭证" → "OAuth 2.0 客户端 ID"
5. 选择 "桌面应用程序" 作为应用程序类型
6. 下载凭证或复制客户端 ID 和客户端密钥
### 2. 环境配置
将您的 OAuth 凭证添加到 `.env` 文件中：
```bash
YOUTUBE_API_KEY=your_api_key_here
YOUTUBE_CLIENT_ID=your_client_id_here
YOUTUBE_CLIENT_SECRET=your_client_secret_here
```
### 3. 身份验证流程
1. 使用 `authenticate_youtube` 工具，设置 `getAuthUrl: true`
2. 在浏览器中打开提供的 URL
3. 登录您的 Google 帐户并授予权限
4. 复制授权代码
5. 再次使用 `authenticate_youtube` 工具，设置 `authCode` 参数
### 4. 使用已身份验证的功能
身份验证后，您可以：
- 创建新播放列表
- 编辑现有的播放列表信息（标题、描述、隐私）
- 将视频添加到您的播放列表中
- 列出您的私人播放列表
- 从播放列表中删除视频
## API 限制
- **配额限制**：YouTube API 有每日配额限制（默认为 10,000 单位/天）
- **速率限制**：API 调用受速率限制
- **OAuth 令牌**：访问令牌过期，需要刷新（自动处理）
- **权限**：OAuth 范围决定了可用的操作
## 开发
### 构建
```bash
npm run build
```
### 开发模式
```bash
npm run dev
```
### 项目结构
```
src/
└── index.ts # 主要服务器实现
build/ # 编译后的 JavaScript 输出
```
## 贡献
1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 彻底测试
5. 提交拉取请求
## 许可证
MIT 许可证 - 请参阅 LICENSE 文件获取详细信息
## 故障排除
### 常见问题
1. **"YOUTUBE_API_KEY 环境变量是必需的"**
- 确保已设置 YOUTUBE_API_KEY 环境变量
- 验证 API 密钥是否有效并具有 YouTube Data API 访问权限
2. **"配额已超出" 错误**
- 您已达到每日 API 配额限制
- 等待配额重置或请求配额增加
3. **"播放列表未找到" 错误**
- 确保播放列表 ID 正确
- 验证播放列表是否为公共（私人播放列表需要 OAuth）
4. **构建错误**
- 确保已安装 Node.js 18+
- 运行 `npm install` 以确保所有依赖项已安装
- 使用 `npm run build` 检查 TypeScript 编译
## 安全考虑
- 永远不要将 API 密钥提交到版本控制中
- 对敏感配置使用环境变量
- 验证所有用户输入
- 实现适当的错误处理和日志记录
---
*此项目使用 GitHub Copilot 创建*
