FFmpeg MCP Server

A Model Context Protocol (MCP) server that provides secure FFmpeg functionality through a sandboxed environment. This server allows AI assistants and other MCP clients to perform video/audio processing tasks using FFmpeg in an isolated environment.

Features

• Sandboxed Execution: All FFmpeg commands run in isolated temporary directories for security
• File Management: Upload, download, and manage files within the sandbox
• Google Cloud Storage Integration: Direct integration with GCS for file transfers
• Security: Only FFmpeg commands are allowed, preventing arbitrary code execution
• RESTful API: Runs as an HTTP server using FastMCP

Installation

Prerequisites

• Python 3.11 or higher
• FFmpeg installed on your system
• (Optional) Google Cloud credentials for GCS features

Setup

1. Clone the repository:

git clone 
cd ffmpeg_mcp

2. Install dependencies using uv (recommended):

uv sync

Or using pip:

pip install -e .

3. (Optional) Set up Google Cloud credentials for GCS integration:

export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/credentials.json"

Usage

Starting the Server

python main.py

The server will start on `localhost:8000` by default.

Available Tools

1. `create_sandbox()`

Creates a new isolated sandbox environment for FFmpeg operations.

Returns: Sandbox directory path

2. `run_ffmpeg_command(sandbox, command)`

Executes FFmpeg commands within the specified sandbox.

Parameters:

• `sandbox` (str): Sandbox directory path
• `command` (str): FFmpeg command to execute

Returns: Command output or error message

3. `put_file(sandbox, filename, content)`

Puts a file into the sandbox environment.

Parameters:

• `sandbox` (str): Sandbox directory path
• `filename` (str): Name of the file to create
• `content` (bytes): File content

Returns: Full path of the created file

4. `get_file(sandbox, filename)`

Retrieves a file from the sandbox environment.

Parameters:

• `sandbox` (str): Sandbox directory path
• `filename` (str): Name of the file to retrieve

Returns: File content as bytes

5. `delete_file(sandbox, filename)`

Deletes a file from the sandbox environment.

Parameters:

• `sandbox` (str): Sandbox directory path
• `filename` (str): Name of the file to delete

Returns: Confirmation message

6. `download_file(sandbox, url, filename)`

Downloads a file from a URL into the sandbox.

Parameters:

• `sandbox` (str): Sandbox directory path
• `url` (str): URL of the file to download
• `filename` (str): Local filename to save as

Returns: Full path of the downloaded file

7. `upload_file(sandbox, filename, upload_url)`

Uploads a file from the sandbox to a specified URL.

Parameters:

• `sandbox` (str): Sandbox directory path
• `filename` (str): Name of the file to upload
• `upload_url` (str): Destination URL

Returns: Upload response

8. `download_file_from_gcs(sandbox, gcs_url, filename)`

Downloads a file from Google Cloud Storage.

Parameters:

• `sandbox` (str): Sandbox directory path
• `gcs_url` (str): GCS URL (gs://bucket/path)
• `filename` (str): Local filename to save as

Returns: Full path of the downloaded file

9. `upload_file_to_gcs(sandbox, filename, gcs_url)`

Uploads a file to Google Cloud Storage.

Parameters:

• `sandbox` (str): Sandbox directory path
• `filename` (str): Name of the file to upload
• `gcs_url` (str): Destination GCS URL

Returns: Confirmation message

Example Workflow

# 1. Create a sandbox
sandbox = create_sandbox()

# 2. Download a video file
download_file(sandbox, "https://example.com/video.mp4", "input.mp4")

# 3. Process with FFmpeg
run_ffmpeg_command(sandbox, "ffmpeg -i input.mp4 -vf scale=720:480 output.mp4")

# 4. Retrieve the processed file
processed_video = get_file(sandbox, "output.mp4")

Security Features

• Command Restriction: Only commands starting with "ffmpeg" are allowed
• Sandbox Isolation: All operations are contained within temporary directories
• Path Validation: Sandbox directories are validated before operations
• Error Handling: Comprehensive error handling for failed operations

Configuration

The server runs on `localhost:8000` by default. You can modify the host and port in the `main.py` file:

if __name__ == "__main__":
    mcp.run(transport="httpx", host="your-host", port=your-port)

Dependencies

• `httpx`: HTTP client for file downloads and uploads
• `mcp[cli]`: Model Context Protocol server framework
• `google-cloud-storage`: Google Cloud Storage integration (optional)