MCP Media Transcoder Engine Server

This specialized MCP server component is designed to interface with FFmpeg for robust media file manipulation, including format conversion and prerequisite validation checks.

Core Capabilities

Prerequisite Verification: Confirms that the FFmpeg executable is correctly installed and available in the system's execution path.
Asset Transformation: Executes conversions for visual and auditory data streams, supporting extensive format sets (e.g., transforming video to MP4/WebM/MOV, audio to MP3, images to PNG).
Capability Enumeration: Provides an interface to retrieve the exhaustive registry of currently supported input and output media types.

System Requirements

Python interpreter version 3.10 or newer.
FFmpeg utility must be installed and discoverable via the system's environment PATH variable.
Utilization of uv for dependency resolution is optional but recommended for swift environment setup.

Installation Protocol

Obtain the source code repository: bash git clone https://github.com/adamanz/mcp-video-converter.git cd mcp-video-converter
Establish and activate an isolated Python environment: ```bash # Standard venv setup python -m venv .venv source .venv/bin/activate # Adjust path for Windows: .venv\Scripts\activate

# Preferred setup using uv uv venv source .venv/bin/activate # Adjust path for Windows: .venv\Scripts\activate ```

Inject required packages: ```bash # Using pip pip install -e . --upgrade pip install fastmcp

# Using uv uv pip install -e . --upgrade uv pip install fastmcp ```

Validate the readiness of the environment: bash # Execute the dedicated installation status script python check_installation.py

Launching the Service Directly

To initiate the server instance manually:

# Ensure the isolated environment is active
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Start the primary server module
python -m mcp_video_converter.server

Integration with Claude Desktop Environment

Follow these steps to register this utility with the Claude Desktop client:

Determine or generate the appropriate configuration manifest: ```bash # For macOS systems mkdir -p ~/Library/Application\ Support/Claude/ nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

# For Windows systems mkdir -p %APPDATA%\Claude\ notepad %APPDATA%\Claude\claude_desktop_config.json ```

Append the server registration block: 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" ] } } }

Windows Host Configuration Variant: json { "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" ] } } }

Crucially, substitute /absolute/path/to/mcp-video-converter with the physical location of the cloned repository.

Relaunch the Claude Desktop application.
The service will appear under the name "video-convert" in the available tools menu.
Key Operational Directives:
Configuration scripts mandate the use of fully qualified file system paths.
Confirm FFmpeg is installed and properly discoverable.
Consult Claude Desktop logs for debugging assistance: ```bash # macOS Log Tail tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

# Windows Log Viewing type %APPDATA%\Claude\logs\mcp*.log ```

Integration with Cursor IDE

To enable this utility within the Cursor environment:

Locate or instantiate the Cursor specific configuration file: ```bash # For macOS/Linux mkdir -p ~/.cursor/ nano ~/.cursor/config.json

# For Windows mkdir -p %USERPROFILE%.cursor\ notepad %USERPROFILE%.cursor\config.json ```

Insert the MCP server definition: 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" ] } } } }

Windows Host Configuration Variant: json { "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" ] } } } }

Ensure path replacement is executed as described previously.

Restart the Cursor IDE.
The transcoder service becomes accessible to Claude's reasoning engine within Cursor.
Critical Configuration Points:
Absolute paths are mandatory for command execution.
FFmpeg must be correctly configured in the system's execution path.
Logging insights can often be found via Cursor's developer console interface.

Deployment via Smithery Platform

Smithery streamlines the operationalization and lifecycle management of MCP services. This repository is fully provisioned for Smithery deployment workflows.

Essential Manifest Files

This project incorporates the necessary configuration artifacts for Smithery deployment:

smithery.yaml: Specifies execution parameters and server startup logic.
Dockerfile: Defines the blueprint for constructing the service's container image.

Smithery YAML Schema Definition

The smithery.yaml file dictates the server invocation strategy:

startCommand:
  type: stdio
  configSchema:
    type: object
    properties:
      ffmpegPath:
        type: string
        title: "FFmpeg Executable Location"
        description: "Optional: Specify the exact file path for FFmpeg (defaults to system PATH search)."
      outputDirectory:
        type: string
        title: "Output Storage Destination"
        description: "Optional: A designated directory path for saving resulting media files."
      quality:
        type: string
        enum: ["low", "medium", "high"]
        default: "medium"
        title: "Default Encoding Fidelity"
  name: "MCP Media Transcoder Engine"
  description: "Toolset for format conversion leveraging FFmpeg and prerequisite validation."
  commandFunction: |
    (config) => {
      // Logic to determine execution parameters based on runtime configuration
    }

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 Service for media manipulation via FFmpeg"
      org.opencontainers.image.licenses: "MIT"

Key Schema Elements: - type: stdio: Designates Standard Input/Output as the communication protocol. - configSchema: Details user-configurable runtime parameters (FFmpeg location, output path, quality setting). - commandFunction: A JavaScript routine that computes the final server startup command contingent on configuration inputs. - build: Configuration section governing the Docker container construction process.

Executing Deployment via Smithery

Acquire the Smithery CLI utility (if not already present): bash # Install the Smithery CLI package globally npm install -g @smithery/cli
Authenticate with the Smithery service: bash smithery login
Deploy directly referencing the repository structure: ```bash # Navigate into the project root cd /path/to/adamanz/mcp-video-converter

# Initiate deployment process smithery deploy ```

Alternative deployment forcing a container rebuild: ```bash # Deploy after building the container image smithery deploy --build

# Deploy with custom parameters passed to the build stage smithery deploy --build --build-arg PYTHON_VERSION=3.11 ```

Configure and activate the service on Smithery: ```bash # Configure server settings interactively smithery configure mcp-video-converter

# Start the remote service instance smithery start mcp-video-converter ```

Docker Containerization Capabilities

This project incorporates a multi-stage Dockerfile engineered for optimal image efficiency. The resulting container:

Leverages multi-stage construction to minimize final image footprint.
Includes both FFmpeg and all Python dependencies.
Establishes a designated volume mount point for all generated output files.
Incorporates a health check mechanism for superior orchestration monitoring.

Manual container build and execution demonstration:

# Build the container image
docker build -t mcp-video-converter .

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

Serverless Deployment Nuances (Smithery Cloud)

When deploying to Smithery's serverless substrate, note these constraints:

Connection Inactivity Timeout: Active connections will terminate after 120 seconds of zero activity.
Storage Volatility: Assume all local storage is temporary and non-persistent.
State Management: The service must maintain a stateless execution model.
Output Retrieval: Converted media artifacts must be correctly serialized and returned within the tool's response payload to ensure client access.

Smithery Operational Commands

Essential commands for ongoing service administration:

# Retrieve real-time server output streams
smithery logs mcp-video-converter

# Update the service to the most recent version
smithery update mcp-video-converter

# Halt the running service instance
smithery stop mcp-video-converter

# Decommission the server registration
smithery remove mcp-video-converter

Access via Smithery Client Applications

Users can interact with the provisioned service through the Smithery graphical client:

Launch the Smithery application.
Navigate to the "Provisioned Services" section.
Select the "mcp-video-converter" entry.
Adjust any necessary parameters (FFmpeg location, output location, quality profile).
Establish the connection.
Utilize the utility via compatible MCP client interfaces.

Local Pre-Deployment Verification

Prior to pushing to Smithery, local validation is strongly advised:

# Test using the MCP Inspector utility (if configured)
mcp-inspector -s /path/to/mcp-video-converter/smithery.yaml

# Or, execute the server locally for functional testing
cd /path/to/mcp-video-converter
python -m mcp_video_converter.server

Diagnosing Typical Failures

Service Discovery Failure

If the host environment fails to locate the MCP server:

Confirm that all configuration files utilize fully qualified, unambiguous file system paths.
Execute the which ffmpeg (or Windows equivalent) command to ensure FFmpeg is reachable.
Verify that the environment activation script executed successfully.
Scrutinize operational logs for detailed error narratives.

Dependency Resolution Errors

If Python module loading errors occur:

Re-verify that all requirements were installed via pip install -e . and pip install fastmcp.
Double-check the activation status of the virtual environment.
Attempt a clean re-installation: pip install -e .

FFmpeg Binary Not Located

If the system reports FFmpeg is missing:

Confirm installation status via which ffmpeg or where ffmpeg.
Manually append the directory containing the FFmpeg binary to the system's PATH variable.
Override the default search by explicitly defining the path in environment variables: json "env": { "PATH": "/usr/local/bin:/usr/bin:/bin:/path/to/ffmpeg/bin" }

Example Invocation Scenarios (Via Claude Integration)

After successful setup, request operations such as:

"Execute the FFmpeg installation verification routine."
"Transform the asset located at /input/source.webm into the MP4 container format, applying the highest fidelity setting."
"Enumerate all accessible output media codecs supported by this utility."

Claude will delegate these instructions to the designated MCP utility calls.

Advanced: Programmatic Access with fastmcp Client

For scripting interactions, utilize the fastmcp command-line utility:

# Request FFmpeg verification status
fastmcp client call <SERVER_URL_OR_FILE_PATH> check_ffmpeg_installed '{"dummy_param": true}'

# Query supported transformation types
fastmcp client call <SERVER_URL_OR_FILE_PATH> get_supported_formats '{"request": "list"}'

# Initiate a media conversion job
fastmcp client call <SERVER_URL_OR_FILE_PATH> convert_video '{ 
  "input_file_path": "/data/input/original.mkv", 
  "output_format": "webm", 
  "quality": "low" 
}'

Remember to substitute <SERVER_URL_OR_FILE_PATH> and provide valid, accessible file paths.

Supported Media Types Registry

Video Containers: MP4, WebM, MOV, AVI, MKV, FLV, Animated GIF
Audio Streams: MP3, WAV, OGG Vorbis, AAC, M4A
Static Images: WebP, JPEG, PNG, BMP, TIFF

Executing Internal Test Suites

# Using standard pip environment
pip install pytest
pytest

# Using uv environment
uv pip install pytest
uv run pytest

Licensing Information

This software artifact is distributed under the permissive MIT License.

Collaboration Guidelines

We welcome external contributions! Refer to CONTRIBUTING.md for detailed contribution guidelines.

mcp-media-transcoder-service

Author

adamanz

Quick Info

Actions

Tags