MCP Media Server

A custom MCP (Model Context Protocol) server for media processing, built with Python. This server enables AI assistants like Claude to interact with media files, perform video processing, and integrate with Supabase and Pinecone for data storage and vector search.

Features

Core Features

- YouTube video downloading using yt-dlp - Video processing with FFmpeg - Supabase integration for metadata storage - Pinecone integration for vector search - MCP server for AI assistant integration

Advanced Features

- Progress tracking for long-running operations - Webhook support for notifications - Batch processing for multiple files - Caching for improved performance - Rate limiting for API protection - User authentication and API key management - Scheduled tasks for maintenance - RESTful API gateway - Continuous operation with Docker - Integration with development IDEs (Roo Code & Windsurf)

Prerequisites

- Python 3.10 or higher
- FFmpeg
- Supabase account
- Pinecone account
- OpenAI API key (for embeddings)
- Docker and Docker Compose (for containerized deployment)

Installation

Option 1: Manual Setup

1. Clone the repository:

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

   cd mcp-media-server

   

2. Create a virtual environment:

   python -m venv venv

   source venv/bin/activate  # On Windows: venv\Scripts\activate

   

3. Install dependencies:

   pip install -r requirements.txt

   

4. Configure the server by copying and editing the example environment file:

   cp .env.example .env

   

5. Edit the .env file to add your API keys and configuration.

Option 2: Docker Setup

1. Clone the repository:

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

   cd mcp-media-server

   

2. Configure the server by copying and editing the example environment file:

   cp .env.example .env

   

3. Edit the .env file to add your API keys and configuration.

4. Build and start the Docker container:

   docker-compose up -d

   

Usage

Running the MCP Server

To run the MCP server:

python main.py

The server uses stdio transport by default for direct integration with Claude Desktop or other MCP clients.

Starting with SSE Transport

To run the server with Server-Sent Events (SSE) transport:

python main.py --transport sse

Running the API Server

To run the API server alongside the MCP server:

python main.py --api

Starting Both SSE and API Server

To run both the SSE transport and API server:

python main.py --transport sse --api

Continuous Operation with Docker

For 24/7 operation in production environments:

1. Deploy using Docker Compose:

   docker-compose up -d

   

2. Set up automatic restarts and monitoring:

   # 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. Set up as a system service (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 Integration (Roo Code & Windsurf)

For Windows users:

1. Run the IDE integration setup script:

   setup_ide_integration.bat

   

For Linux/macOS users:

1. Generate an API key:

   ./generate_api_key.sh

   

2. Configure your IDE using the generated key and settings from ide-config.json

Integrating with Claude Desktop

1. Open Claude Desktop app
2. Navigate to Settings
3. Add a new MCP server with the following configuration:
- Name: MCP Media Server
- Command: Path to your Python executable
- Arguments: Path to the main.py file

Example configuration:

{

  "mcpServers": {

    "mcp-media-server": {

      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",

      "args": ["C:\\path\\to\\mcp-media-server\\main.py"]

    }

  }

}

API Documentation

Once the API server is running, you can access the API documentation at:

http://localhost:9000/docs

Key API Endpoints

- /videos/download - Download a video from YouTube
- /videos/process - Process a video using FFmpeg
- /videos/search - Search for videos on YouTube
- /videos/vector-search - Semantic search for videos
- /videos/similar - Find similar videos

Development

Project Structure

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

Adding New Tools

To add a new tool to the MCP server, create a new function in the appropriate file in the src/tools directory and decorate it with @mcp_server.register_tool.

Example:

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

Container Management

View logs:

docker-compose logs -f mcp-server

Check container status:

docker ps | grep mcp-server

Monitor resource usage:

docker stats mcp-server

License

This project is licensed under the MIT License - see the LICENSE file for details.