MCP Media Server

MCP Media Server

一个使用 Python 构建的自定义 MCP（Model Context Protocol）服务，用于媒体处理。此服务可让 Claude 等 AI 助手与媒体文件交互、执行视频处理，并集成 Supabase 和 Pinecone，以实现数据存储和向量搜索。

功能

核心功能

• 使用 yt-dlp 下载 YouTube 视频
• 使用 FFmpeg 处理视频
• 集成 Supabase 以存储元数据
• 集成 Pinecone 以进行向量搜索
• MCP 服务，可与 AI 助手集成

高级功能

• 跟踪长时间运行操作的进度
• 支持通过 Webhook 发送通知
• 批量处理多个文件
• 通过缓存提升性能
• 通过速率限制保护 API
• 用户身份验证和 API 密钥管理
• 用于维护的计划任务
• RESTful API 网关
• 通过 Docker 持续运行
• 与开发 IDE（Roo Code 和 Windsurf）集成

前置条件

• Python 3.10 或更高版本
• FFmpeg
• Supabase 账户
• Pinecone 账户
• OpenAI API 密钥（用于生成嵌入）
• Docker 和 Docker Compose（用于容器化部署）

安装

选项 1：手动设置

1. 克隆仓库：

   git clone https://github.com/yourusername/mcp-media-server.git
   cd mcp-media-server
   

2. 创建虚拟环境：

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. 安装依赖：

   pip install -r requirements.txt
   

4. 复制示例环境文件并编辑，以配置服务：

   cp .env.example .env
   

5. 编辑 .env 文件，添加你的 API 密钥和配置。

选项 2：Docker 设置

1. 克隆仓库：

   git clone https://github.com/yourusername/mcp-media-server.git
   cd mcp-media-server
   

2. 复制示例环境文件并编辑，以配置服务：

   cp .env.example .env
   

3. 编辑 .env 文件，添加你的 API 密钥和配置。

4. 构建并启动 Docker 容器：

   docker-compose up -d
   

使用

运行 MCP 服务

运行 MCP 服务：

python main.py

默认情况下，服务使用 stdio 传输，以便直接与 Claude Desktop 或其他 MCP 客户端集成。

使用 SSE 传输启动

使用 Server-Sent Events（SSE）传输运行服务：

python main.py --transport sse

运行 API 服务

在运行 MCP 服务的同时运行 API 服务：

python main.py --api

同时启动 SSE 和 API 服务

同时运行 SSE 传输和 API 服务：

python main.py --transport sse --api

使用 Docker 持续运行

在生产环境中实现全天候运行：

1. 使用 Docker Compose 部署：

   docker-compose up -d
   

2. 设置自动重启和监控：

   # Make scripts executable
   chmod +x deploy.sh monitor.sh generate_api_key.sh
   
   # Deploy with health checks
   ./deploy.sh
   
   # Add monitoring to crontab (runs every 5 minutes)
   (crontab -l 2>/dev/null; echo "*/5 * * * * /path/to/mcp-media-server/monitor.sh") | crontab -
   

3. 设置为系统服务（Linux）：

   # Copy service file
   sudo cp mcp-media-server.service /etc/systemd/system/
   
   # Edit the service file to update the path
   sudo nano /etc/systemd/system/mcp-media-server.service
   
   # Enable and start the service
   sudo systemctl enable mcp-media-server.service
   sudo systemctl start mcp-media-server.service
   

IDE 集成（Roo Code 和 Windsurf）

Windows 用户：

1. 运行 IDE 集成设置脚本：

   setup_ide_integration.bat
   

Linux/macOS 用户：

1. 生成 API 密钥：

   ./generate_api_key.sh
   

2. 使用生成的密钥和 ide-config.json 中的设置配置 IDE

与 Claude Desktop 集成

1. 打开 Claude Desktop 桌面应用
2. 前往“设置”
3. 添加新的 MCP 服务，并使用以下配置：
   • 名称：MCP Media Server
   • 命令：Python 可执行文件的路径
   • 参数：main.py 文件的路径

配置示例：

{
  "mcpServers": {
    "mcp-media-server": {
      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\mcp-media-server\\main.py"]
    }
  }
}

API 文档

API 服务运行后，可通过以下地址访问 API 文档：

http://localhost:9000/docs

主要 API 端点

• /videos/download - 从 YouTube 下载视频
• /videos/process - 使用 FFmpeg 处理视频
• /videos/search - 在 YouTube 上搜索视频
• /videos/vector-search - 对视频进行语义搜索
• /videos/similar - 查找相似视频

开发

项目结构

mcp-media-server/
├── src/
│   ├── api/              # RESTful API implementation
│   ├── auth/             # Authentication and security
│   ├── core/             # Core MCP server implementation
│   ├── config/           # Configuration settings
│   ├── db/               # Database integrations
│   ├── services/         # Background services
│   ├── tasks/            # Scheduled tasks
│   ├── tools/            # MCP tools implementation
│   ├── utils/            # Utilities and helpers
│   └── webhooks/         # Webhook handlers
├── downloads/            # Downloaded files
├── processed/            # Processed files
├── thumbnails/           # Generated thumbnails
├── cache/                # Cache files
├── logs/                 # Log files
├── .env                  # Environment variables
├── docker-compose.yml    # Docker configuration
├── Dockerfile            # Docker build instructions
├── deploy.sh             # Deployment script
├── monitor.sh            # Health monitoring script
├── generate_api_key.sh   # API key generation script
├── mcp-media-server.service # Systemd service file
├── setup_ide_integration.bat # IDE integration for Windows
├── ide-config.json       # Configuration for IDE integration
├── main.py               # Application entry point
└── requirements.txt      # Python dependencies

添加新工具

若要向 MCP 服务添加新工具，请在 src/tools 目录中的相应文件里创建新函数，并使用 @mcp_server.register_tool 装饰该函数。

示例：

from src.core.server import mcp_server

@mcp_server.register_tool
async def my_new_tool(param1: str, param2: int) -> dict:
    """
    Description of the new tool.
    
    Args:
        param1: Description of param1
        param2: Description of param2
        
    Returns:
        Dict containing the result
    """
    # Implement the tool functionality
    result = {"status": "success", "message": "Tool executed successfully"}
    return result

容器管理

查看日志：

docker-compose logs -f mcp-server

检查容器状态：

docker ps | grep mcp-server

监控资源使用情况：

docker stats mcp-server

许可证

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