MCP Video Converter Server

Convert video files between various formats using FFmpeg. Requires FFmpeg to be installed on the system.

An MCP server that provides tools for checking FFmpeg installation and converting video files between various formats.

- Check FFmpeg: Verifies if FFmpeg is installed and accessible.
- Convert Video: Converts video, audio, and image files to various formats (e.g., MP4, WebM, MOV, MP3, PNG).
- Format Info: Get a list of supported file formats for conversion.

- Python 3.10+
- FFmpeg installed and available in your system's PATH
- [Optional]uvfor environment management

git clone https://github.com/adamanz/mcp-video-converter.git cd mcp-video-converter

# Using venv (standard library) python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Or using uv (recommended if available) uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate

# Using pip pip install -e . pip install fastmcp # Or using uv uv pip install -e . uv pip install fastmcp

# Run the installation check script python check_installation.py

# Activate the virtual environment if not already activated source .venv/bin/activate # On Windows: .venv\Scripts\activate # Run the server python -m mcp_video_converter.server

# macOS mkdir -p ~/Library/Application\ Support/Claude/ nano ~/Library/Application\ Support/Claude/claude_desktop_config.json # Windows mkdir -p %APPDATA%\Claude\ notepad %APPDATA%\Claude\claude_desktop_config.json

{ "mcpServers": { "video-convert": { "command": "/bin/bash", "args": [ "-c", "cd /absolute/path/to/mcp-video-converter && source .venv/bin/activate && python -m mcp_video_converter.server" ] } } }

{ "mcpServers": { "video-convert": { "command": "cmd.exe", "args": [ "/c", "cd /d C:\\absolute\\path\\to\\mcp-video-converter && .venv\\Scripts\\activate && python -m mcp_video_converter.server" ] } } }

Replace/absolute/path/to/mcp-video-converterwith the absolute path to your repository.

- The server will appear as "video-convert" in the MCP tools menu

- Always use absolute paths in your configuration
- Make sure FFmpeg is installed and in your PATH
- If you encounter issues, check the Claude Desktop logs:

# macOS tail -n 20 -F ~/Library/Logs/Claude/mcp.log # Windows type %APPDATA%\Claude\logs\mcp.log

-

Locate or create the Cursor configuration file:

# macOS mkdir -p ~/.cursor/ nano ~/.cursor/config.json # Windows mkdir -p %USERPROFILE%\.cursor\ notepad %USERPROFILE%\.cursor\config.json

{ "ai": { "mcpServers": { "video-convert": { "command": "/bin/bash", "args": [ "-c", "cd /absolute/path/to/mcp-video-converter && source .venv/bin/activate && python -m mcp_video_converter.server" ] } } } }

{ "ai": { "mcpServers": { "video-convert": { "command": "cmd.exe", "args": [ "/c", "cd /d C:\\absolute\\path\\to\\mcp-video-converter && .venv\\Scripts\\activate && python -m mcp_video_converter.server" ] } } } }

Replace/absolute/path/to/mcp-video-converterwith the absolute path to your repository.

- The server will be available to Claude in Cursor

- Always use absolute paths in your configuration
- Make sure FFmpeg is installed and in your PATH
- Logs may be accessed through Cursor's developer tools

Smithery is a platform that simplifies deploying and managing MCP servers. This project is fully configured for Smithery deployment with the required files and configurations.

This project includes all required configuration files for Smithery deployment:
- smithery.yaml: Defines how to start your server and its configuration options
- Dockerfile: Defines how to build your server's container image

Thesmithery.yamlfile provides Smithery with instructions on how to run your server:

startCommand: type: stdio configSchema: type: object properties: ffmpegPath: type: string title: "FFmpeg Path" description: "Optional path to FFmpeg executable (uses system PATH by default)" outputDirectory: type: string title: "Output Directory" description: "Optional custom directory for output files" quality: type: string enum: ["low", "medium", "high"] default: "medium" title: "Default Quality" name: "MCP Video Converter" description: "Convert video files between formats and check FFmpeg installation" commandFunction: | (config) => { // Function that returns command details based on configuration options } build: dockerfile: Dockerfile dockerBuildPath: . env: OUTPUT_DIRECTORY: "/data/converted" buildOptions: buildArgs: PYTHON_VERSION: "3.10" INSTALL_DEV: "false" labels: org.opencontainers.image.source: "https://github.com/adamanz/mcp-video-converter" org.opencontainers.image.description: "MCP Server for video conversion using FFmpeg" org.opencontainers.image.licenses: "MIT"

- type: stdio: Defines that our server uses the standard I/O transport
- configSchema: Defines the configuration options users can set (FFmpeg path, output directory, quality)
- commandFunction: JavaScript function that returns how to start the server based on configuration
- build: Container-specific configuration for Dockerized deployment
-

Install Smithery CLI if you haven't already:

# Install the Smithery command-line tool npm install -g @smithery/cli

# Navigate to the repository directory cd /path/to/adamanz/mcp-video-converter # Deploy to Smithery smithery deploy

Alternatively, deploy with explicit build options:

# Deploy with container build smithery deploy --build # Deploy with custom build arguments smithery deploy --build --build-arg PYTHON_VERSION=3.11

Configure and start the server in Smithery:

# Configure the server (interactive) smithery configure mcp-video-converter # Start the server smithery start mcp-video-converter

This project includes a multi-stage Dockerfile for efficient containerized deployment. The container:

- Uses a multi-stage build process to reduce final image size
- Installs FFmpeg and all required dependencies
- Creates a dedicated volume mount point for converted files
- Includes a healthcheck for better container monitoring

You can build and run the Docker container manually:

# Build the container docker build -t mcp-video-converter . # Run the container docker run -it --rm \ -v $(pwd)/converted:/data/converted \ -e FFMPEG_PATH=/usr/bin/ffmpeg \ -e DEFAULT_QUALITY=high \ mcp-video-converter

When deploying to Smithery's serverless environment, be aware of the following:

- Connection Timeout: Connections to your server will timeout after 2 minutes of inactivity
- Ephemeral Storage: Design your server with ephemeral storage in mind
- Stateless Design: The server should not rely on persistent local storage
- Output Files: Video conversion outputs should be returned properly as part of the tool response to ensure clients can access them

Useful Smithery commands for managing your deployment:

# View server logs smithery logs mcp-video-converter # Update to latest version smithery update mcp-video-converter # Stop the server smithery stop mcp-video-converter # Remove the server smithery remove mcp-video-converter

Users can access your server through the Smithery app:
- Open the Smithery application
- Navigate to "Servers" tab
- Select "mcp-video-converter"
- Configure settings if prompted (FFmpeg path, output directory, quality)
- Connect to the server
- Use the server with compatible MCP clients

Before deploying to Smithery, it's recommended to test your server locally:

# Test with MCP Inspector (if available) mcp-inspector -s /path/to/mcp-video-converter/smithery.yaml # Or test by running the server directly cd /path/to/mcp-video-converter python -m mcp_video_converter.server

If the MCP server is not being picked up:
- Verify the paths in your configuration file are absolute and correct
- Check that FFmpeg is installed and in your PATH
- Ensure the virtual environment is activated in your command
- Check the logs for specific error messages

If you see errors about missing modules:
- Make sure you installed all dependencies withpip install -e .andpip install fastmcp
- Verify the virtual environment is being activated correctly
- Try reinstalling the package:pip install -e .
- Verify FFmpeg is installed:which ffmpegorwhere ffmpegon Windows
- Add the FFmpeg directory to your PATH
- In the configuration, you can specify the full path to FFmpeg:

"env": { "PATH": "/usr/local/bin:/usr/bin:/bin:/path/to/ffmpeg/bin" }

Once integrated, you can ask Claude to perform tasks like:
- "Check if FFmpeg is installed on my system"
- "Convert this video file: /path/to/video.webm to MP4 format with high quality"
- "What video formats can I convert to?"

Claude will use the appropriate tools from the MCP server to accomplish these tasks.

For programmatic usage, you can use the fastmcp client:

# Check FFmpeg installation fastmcp client call <SERVER_URL_OR_FILE_PATH> check_ffmpeg_installed '{}' # Get supported formats fastmcp client call <SERVER_URL_OR_FILE_PATH> get_supported_formats '{}' # Convert a video fastmcp client call <SERVER_URL_OR_FILE_PATH> convert_video '{ "input_file_path": "/path/to/your/video.webm", "output_format": "mp4", "quality": "high" }'

Replace/path/to/your/video.webmwith an actual video file path.

- Video: MP4, WebM, MOV, AVI, MKV, FLV, GIF
- Audio: MP3, WAV, OGG, AAC, M4A
- Image: WebP, JPG, PNG, BMP, TIFF

# Using pip pip install pytest pytest # Using uv uv pip install pytest uv run pytest

This project is open source and available under theMIT License.

Contributions are welcome! Please seeCONTRIBUTING.mdfor details on how to contribute to this project.

An MCP server integration for the DaVinci Resolve video editing software.