内容
# YouTube Gemini MCP 服务器
[](https://badge.fury.io/py/youtube-gemini-mcp)
一个基于模型上下文协议（MCP）的服务器，提供使用Gemini 2.5 Pro的对话式YouTube视频分析能力。通过多轮对话分析视频，具有先进的视觉理解。
## 🎯 解决的问题
### 传统视频分析的痛点
❌ **仅限于文字记录** - 缺失视觉上下文和场景理解
❌ **没有对话记忆** - 每次分析都从头开始
❌ **手动工作流程** - 复杂的下载/上传过程
### 我们的解决方案
✅ **完整的视频分析** - 视觉、音频和上下文理解
✅ **会话记忆** - 自动在之前的分析基础上继续
✅ **集成工作流程** - 从YouTube网址到分析，一步到位
## 🚀 关键能力
### 🔄 基于会话的视频对话
创建持久会话，进行多轮视频分析：
```python
# 创建会话
create_video_session(
description="分析机器学习讲座",
video_source="https://youtube.com/watch?v=abc123",
source_type="youtube_url"
)
# 继续对话
analyze_video_in_session(session_id="uuid", prompt="关键概念是什么？")
analyze_video_in_session(session_id="uuid", prompt="解释神经网络部分")
```
### 📹 直接处理YouTube视频
无需下载 - 直接处理YouTube视频：
```python
analyze_youtube_video(
youtube_url="https://youtube.com/watch?v=abc123",
prompt="总结视频的主要内容"
)
```
### 💾 本地视频支持
上传并分析本地视频文件（保留48小时）：
```python
analyze_local_video(
video_path="/path/to/video.mp4",
prompt="视频中发生了什么？"
)
```
## 🛠️ 安装
### 前提条件
- Python 3.10+
- Google AI API 密钥
- Poetry（推荐）或 pip
### 设置
```bash
# 克隆仓库
git clone https://github.com/aigentive/youtube-gemini-mcp
cd youtube-gemini-mcp
# 使用Poetry安装
poetry install
# 或使用pip
pip install -e .
# 设置环境变量
export GOOGLE_API_KEY="your_google_api_key_here"
```
## 🔧 Claude Desktop 集成
### 快速设置
1. **获取Google AI API密钥**：访问 [Google AI Studio](https://ai.google.dev/) 获取免费的API密钥
2. **添加到Claude Desktop**：将以下配置复制到Claude Desktop设置中
### 生产环境配置
将以下内容添加到Claude Desktop MCP配置（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"youtube-gemini-mcp": {
"command": "youtube-gemini-mcp",
"env": {
"GOOGLE_API_KEY": "your_google_api_key_here"
}
}
}
}
```
### 开发环境配置
在开发过程中，使用Poetry配置：
```json
{
"mcpServers": {
"youtube-gemini-mcp-dev": {
"command": "poetry",
"args": ["run", "python", "-m", "youtube_gemini_mcp.server"],
"cwd": "/absolute/path/to/youtube-gemini-mcp",
"env": {
"GOOGLE_API_KEY": "your_google_api_key_here",
"LOG_LEVEL": "DEBUG"
}
}
}
}
```
### 配置模板
我们提供现成的配置文件：
- **开发环境**：`mcp-config.poetry.json` - 用于本地开发
- **生产环境**：`mcp-config.private.json.example` - 复制并自定义
## 📚 可用工具
| 工具 | 描述 |
|------|-------------|
| `create_video_session` | 创建新的对话式分析会话 |
| `analyze_video_in_session` | 在会话上下文中分析视频 |
| `analyze_youtube_video` | 单次YouTube视频分析 |
| `analyze_local_video` | 单次本地视频分析 |
| `get_session_status` | 获取会话信息和历史 |
| `list_active_sessions` | 列出所有活动会话 |
| `close_session` | 关闭会话并清理资源 |
| `validate_youtube_url` | 验证和标准化YouTube网址 |
| `get_usage_guide` | 综合文档 |
| `get_server_stats` | 服务器健康状况和统计信息 |
## 🎯 使用场景
### 教育内容分析
分析讲座、教程和教育视频，并提出后续问题。
### 内容研究
系统地研究纪录片、访谈和信息内容。
### 视频总结
从长篇内容中提取关键见解并创建总结。
### 培训材料开发
分析现有的培训视频，以提取学习目标和关键点。
## ⚡ 快速示例
### 分析YouTube视频
```python
# 直接分析 - 适合快速获取见解
analyze_youtube_video(
youtube_url="https://youtube.com/watch?v=dQw4w9WgXcQ",
prompt="这个视频是关于什么的？提供一个全面的总结。"
)
```
### 基于会话的分析
```python
# 创建持久会话，进行多轮对话
session = create_video_session(
description="学习机器学习基础知识",
video_source="https://youtube.com/watch?v=abc123",
session_name="ML Fundamentals Study"
)
# 通过对话建立理解
analyze_video_in_session(
session_id=session["session_id"],
prompt="本讲座中涵盖的主要主题是什么？"
)
analyze_video_in_session(
session_id=session["session_id"],
prompt="关注神经网络部分 - 如何解释它们？"
)
analyze_video_in_session(
session_id=session["session_id"],
prompt="展示了哪些实用示例或演示？"
)
analyze_video_in_session(
session_id=session["session_id"],
prompt="根据我们的讨论，初学者的关键收获是什么？"
)
```
### 本地视频分析
```python
# 上传并分析私有内容
analyze_local_video(
video_path="/path/to/your/presentation.mp4",
prompt="提取本季度审查中的关键业务指标和建议。"
)
```
### 高级：特定时间戳分析
```python
# 关注特定视频片段
analyze_video_in_session(
session_id="your-session-id",
prompt="分析此片段中显示的演示",
timestamp_range="5:30-8:45"
)
```
## 🔐 配置
### 环境变量
**必填**：
- `GOOGLE_API_KEY` - 从 [Google AI Studio](https://ai.google.dev/) 获取免费的API密钥
**可选配置**：
```bash
MCP_MAX_SESSIONS=50 # 最大并发会话数
MCP_SESSION_TIMEOUT=7200 # 会话超时时间（秒）
GEMINI_MODEL_DEFAULT="gemini-2.5-pro-preview-05-06" # 默认Gemini模型
MAX_VIDEO_DURATION=7200 # 最大视频长度（秒）
AUTO_CLEANUP_FILES=true # 自动清理上传的文件
LOG_LEVEL=INFO # 日志级别（DEBUG，INFO，WARNING，ERROR）
```
### 系统要求
- **Python**：3.10+（推荐3.11+）
- **内存**：4GB RAM（视频处理最低要求）
- **存储**：500MB（用于会话数据和临时文件）
- **网络**：高速互联网（用于视频处理）
### 限制和约束
#### YouTube视频（无限会话）
- ✅ **无文件大小限制** - 直接URL处理
- ✅ **无限会话时长** - 无48小时限制
- ⚠️ **2小时视频限制** - 推荐最大视频长度为2小时
- ⚠️ **仅限公开视频** - 私有/未列出的视频可能无法访问
#### 本地视频（48小时会话）
- ⚠️ **2GB文件大小限制** - Google Files API限制
- ⚠️ **48小时自动删除** - 文件在48小时后自动删除
- ⚠️ **20GB项目限制** - 每个Google项目的总存储配额
- ❌ **无法延长保留期** - 无法将文件寿命延长超过48小时
#### 性能指南
- **并发会话**：默认最大50个活动会话
- **会话超时**：2小时不活动后清理
- **内存使用**：每个活动会话约100MB
- **响应时间**：典型分析请求的响应时间为10-30秒
## 🧪 测试
```bash
# 运行测试
poetry run pytest
# 带有覆盖率测试
poetry run pytest --cov=youtube_gemini_mcp
# 类型检查
poetry run mypy src/
```
## 📄 许可证
该项目使用MIT许可证 - 参见 [LICENSE](LICENSE) 文件获取详细信息。
## 🔗 相关项目
- [MCP 规范](https://github.com/modelcontextprotocol/specification)
- [Claude Desktop](https://claude.ai/desktop)
- [Google Gemini API](https://ai.google.dev/)
## 📚 文档
- **[LLM.md](LLM.md)** - AI系统的综合使用指南
- **[DEVELOPMENT.md](DEVELOPMENT.md)** - 开发设置和架构
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - 如何为项目做出贡献
- **[PRD.md](PRD.md)** - 完整的产品需求文档
## 🤝 贡献
我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。
### 贡献者快速入门
1. 复刻仓库
2. 设置开发环境：`poetry install`
3. 运行测试：`poetry run pytest`
4. 进行更改并添加测试
5. 提交拉取请求
## 📞 支持与社区
- 🐛 **错误报告**：[GitHub Issues](https://github.com/aigentive/youtube-gemini-mcp/issues)
- 💡 **功能请求**：[GitHub Issues](https://github.com/aigentive/youtube-gemini-mcp/issues)
- 💬 **讨论**：[GitHub Discussions](https://github.com/aigentive/youtube-gemini-mcp/discussions)
- 📖 **文档**：查看上面的综合文档
### 获取帮助
1. **查看文档**：从 [LLM.md](LLM.md) 开始，获取使用问题
2. **搜索问题**：在GitHub Issues中查找现有解决方案
3. **创建问题**：提供清晰的细节和重现步骤
4. **社区**：加入讨论，提出一般性问题和想法
