使用说明
YouTube MCP服务器
用于YouTube操作的模型上下文协议（MCP）服务器，提供从YouTube视频中提取字幕、主题和播放列表信息的工具。
特性
- 提取YouTube字幕：从支持多语言的YouTube视频中检索字幕/字幕
- 提取视频主题：解析视频描述以提取主题、部分和时间戳
- 提取播放列表标题：从YouTube播放列表中的所有视频获取标题和元数据
需求
- Python 3.11或更高版本
- 来自谷歌云平台的YouTube数据API v3密钥
- UV包管理器（推荐）
- Claude Desktop（用于MCP集成）
安装
1.克隆存储库
git clone <repository-url>
cd "Youtube MCP"
2.使用UV安装依赖项
uv sync
3.设置环境变量
创建一个 .env 项目根目录中的文件：
YOUTUBE_API_KEY=your_youtube_api_key_here
获取YouTube API密钥
- 首选 谷歌云控制台
- 创建新项目或选择现有项目
- 启用YouTube数据API v3
- 创建凭据（API密钥）
- 将API密钥复制到
.env文件
Claude桌面配置
1.找到Claude桌面配置
配置文件位于：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%/Claude/claude_desktop_config.json
2.添加MCP服务器配置
将以下内容添加到您的Claude Desktop配置中：
{
"mcpServers": {
"youtube-mcp": {
"command": "/Users/yourusername/.local/bin/uv",
"args": [
"--directory",
"/absolute/path/to/Youtube MCP",
"run",
"python",
"-m",
"youtube_mcp.server"
]
}
}
}
重要提示：
- 替换
/Users/yourusername/.local/bin/uv使用您的实际紫外线路径（查找which uv) - 替换
/absolute/path/to/Youtube MCP包含项目的完整路径 - 仅使用绝对路径-相对路径不起作用
3.重新启动克劳德桌面
完全退出并重新启动Claude Desktop以使更改生效。
用法
测试安装
首先，独立测试核心功能：
uv run python tests/test_functions.py
与Claude Desktop一起使用
配置后，您可以在Claude Desktop对话中直接使用YouTube MCP工具：
提取YouTube字幕
Extract captions from https://www.youtube.com/watch?v=VIDEO_ID in Spanish
参数：
video_url：YouTube视频URL（必填）language_preference：语言代码，如'en'、'es'、'fr'（可选，默认为'en'）
提取视频主题
Extract topics and timestamps from https://www.youtube.com/watch?v=VIDEO_ID
参数：
video_url：YouTube视频URL（必填）
提取播放列表标题
Get all video titles from https://www.youtube.com/playlist?list=PLAYLIST_ID
参数：
playlist_url：YouTube播放列表URL（必填）
支持的URL格式
服务器接受各种YouTube URL格式：
https://www.youtube.com/watch?v=VIDEO_IDhttps://youtu.be/VIDEO_IDhttps://www.youtube.com/playlist?list=PLAYLIST_ID- 具有附加参数的URL（例如。，
&si=...,&t=...)
错误处理
服务器优雅地处理：
- ❌ 无效的YouTube URL
- ❌ 私人或不可用的视频
- ❌ 没有字幕的视频
- ❌ API配额限制
- ❌ 网络连接问题
- ❌ 格式错误的播放列表URL
所有错误都会返回带有有用错误消息的结构化响应。
项目结构
Youtube MCP/
├── src/
│ └── youtube_mcp/
│ ├── __init__.py # Package exports
│ ├── server.py # FastMCP server with 3 tools
│ ├── youtube_client.py # YouTube API wrapper
│ └── utils.py # Helper functions
├── tests/
│ └── test_functions.py # Comprehensive function tests
├── .env # Environment variables (API keys)
├── .gitignore # Git ignore patterns
├── CLAUDE.md # Project instructions for Claude
├── PROJECT_LOG.md # Development progress log
├── README.md # This file
├── pyproject.toml # UV/Python project configuration
└── uv.lock # Auto-generated lock file
发展
运行测试
# Test core functions
uv run python tests/test_functions.py
# Run pytest (if available)
uv run pytest
代码质量
# Format code
uv run black .
# Lint code
uv run ruff check .
手动服务器测试
您可以独立运行MCP服务器进行测试：
uv run python -m youtube_mcp.server
故障排除
常见问题
1.“spawn uv ENOONT”错误
- 在Claude Desktop配置中使用uv的绝对路径
- 使用以下命令查找uv路径：
which uv
2.JSON解析错误
- 确保服务器代码中没有打印语句
- 所有输出到stdout的都必须是有效的JSON
3.“需要YOUTUBE_API_KEY环境变量”
- 检查
.env文件存在并且具有正确的API密钥 - 在Google云控制台中验证API密钥是否有效
4.服务器没有响应
- 完全重新启动克劳德桌面
- 在Claude Desktop设置中检查MCP服务器日志
查看日志
Claude Desktop日志可在以下位置获得：
- macOS：克劳德桌面设置→ 开发者→ 查看日志
- 寻找
[youtube-mcp]条目
API限值
YouTube Data API v3具有配额：
- 默认值：每天10000个单位
- 视频元数据：每个请求约1-5个单位
- 播放列表项目：每50个视频约1个
监控中的使用情况 谷歌云控制台.
技术细节
- MCP协议：使用stdio传输进行Claude Desktop集成
- FastMCP：采用FastMCP框架构建，实现强大的MCP服务器功能
- yt-dlp：支持多语言字幕提取
- YouTube API v3：处理视频元数据和播放列表操作
- 错误处理：具有结构化错误响应的多层方法
贡献
- 分叉存储库
- 创建要素分支
- 安装开发依赖项：
uv sync - 进行更改并彻底测试
- 运行代码质量检查：
uv run black .和uv run ruff check . - 提交拉取请求
许可证
MIT许可证-有关详细信息，请参阅许可证文件。
