MCP Video Agent

🎥 MCP视频代理

一个强大的AI驱动的视频分析系统 双子座2.5闪光灯, ElevenLabs TTS，以及 Gemini上下文缓存 用于智能视频问答。

🎯 概述

该项目实现了一个与MCP（模型上下文协议）兼容的视频代理，可以：

• 🎬 使用谷歌的Gemini 2.5 Flash（多模式AI）分析视频内容
• 🗣️ 使用ElevenLabs文本转语音生成语音响应
• ⚡ 利用Gemini的上下文缓存，将重复查询速度提高2-3倍
• 🔌 作为Claude Desktop集成的MCP服务器
• 🌐 提供两种部署选项：Modal（后端）+Gradio（前端），或独立的HF Space

🏗️ 建筑

选项1：分布式（模态+HF空间前端）

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Gradio UI     │    │    Modal        │    │   Gemini 2.5    │
│ (HF Space)      │◄──►│   Backend       │◄──►│  Flash + Cache  │
│                 │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

选项2：独立（仅限高频空间）

┌─────────────────────────────────┐    ┌─────────────────┐
│   Gradio UI + Backend Logic     │    │   Gemini 2.5    │
│        (HF Space)                │◄──►│  Flash + Cache  │
│                                  │    │                 │
└─────────────────────────────────┘    └─────────────────┘

组件

• 前端：Gradio网络界面，用于视频上传和对话问答
• 后端（可选模式）：具有持久存储的无服务器视频处理
• AI堆栈:

- 用于视频分析的Google Gemini 2.5 Flash - Gemini上下文缓存，用于高效重复查询 - ElevenLabs用于自然语音响应

🚀 快速部署

选项1：部署到拥抱面部空间（建议快速启动）

cd hf_space
chmod +x deploy.sh
./deploy.sh YOUR_HF_USERNAME

然后在“空间设置”中配置机密：

• GOOGLE_API_KEY （必填）-从获取 谷歌人工智能工作室
• ELEVENLABS_API_KEY （可选）-从获取 十一实验室

选项2：将后端部署到模态+前端部署到高频空间

后端：

cd backend
modal deploy modal_app.py

前端：

cd frontend
# Set MODAL_BACKEND_URL in your HF Space settings
# Then upload frontend/ directory to your Space

配置

• API双子星：从获取API密钥 谷歌人工智能工作室
• ElevenLabs API：从获取API密钥 十一实验室 （可选）
• 模态秘密：使用配置API密钥 modal secret create

📁 项目结构

mcp-video-agent/
├── backend/                # Modal backend (optional distributed deployment)
│   ├── modal_app.py        # Video processing + Gemini Context Caching
│   ├── requirements.txt    # Backend dependencies
│   └── cookies.txt         # (Optional) YouTube cookies for yt-dlp
├── frontend/               # Gradio interface (connects to Modal backend)
│   ├── app.py              # Main Gradio application
│   └── requirements.txt    # Frontend dependencies
├── hf_space/               # 🌟 Standalone HF Space deployment (recommended)
│   ├── app.py              # All-in-one Gradio + Backend
│   ├── requirements.txt    # Python dependencies
│   ├── README.md           # Space description
│   ├── DEPLOYMENT.md       # Deployment guide
│   ├── deploy.sh           # Automated deployment script
│   └── .gitignore          # HF Space specific ignores
├── .gitignore              # Git ignore rules
└── README.md               # This file

🔌 在Claude Desktop中用作MCP服务器

部署到HF Space后，将此添加到您的Claude Desktop配置中：

macOS/Linux： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "video-agent": {
      "url": "https://YOUR_USERNAME-mcp-video-agent.hf.space/sse"
    }
  }
}

窗户： %APPDATA%\Claude\claude_desktop_config.json

⚡ 性能和成本

带上下文缓存的Gemini 2.5 Flash

• 第一个查询：每个视频约0.05-0.15美元（全处理）
• 后续查询 （1小时内）：每次查询约0.005-0.015美元（成本降低90%！）
• 速度提升：缓存查询速度提高2-3倍

ElevenLabs TTS

• 成本：每1000个字符约0.18美元
• 可选的：无需TTS（纯文本响应）即可正常工作

🛠️ 发展

本地测试（仅限前端）

cd frontend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
python app.py

本地测试（HF空间版）

cd hf_space
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
export GOOGLE_API_KEY=your_key_here
export ELEVENLABS_API_KEY=your_key_here
python app.py

📊 功能比较

🤝 贡献

欢迎投稿！拜托：

1. 复刻仓库
2. 创建要素分支
3. 进行更改
4. 提交拉取请求

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🙏 致谢

内置：

• 谷歌双子座2.5 Flash -具有上下文缓存的多模态AI
• 十一实验室 -自然语音合成
• 格拉迪奥 -漂亮的web UI框架
• 模态 -无服务器计算（可选后端）
• 拥抱脸 -AI社区和托管

📚 文档

• 高频空间部署：参见 hf_space/DEPLOYMENT.md
• 模态后端：参见 backend/modal_app.py 评论
• 前端集成：参见 frontend/app.py 评论

🆘 支持

如果您遇到问题：

1. 检查HF Space仪表板中的日志
2. 验证在机密中是否正确设置了API密钥
3. 审查 hf_space/DEPLOYMENT.md 有关故障排除提示
4. 在GitHub上打开一个带有详细错误消息的问题

______________________________________________________________________

⭐ 如果你觉得这个项目有用，请在GitHub上加星！