videoworker MCP

Give your AI agent FFmpeg: upload local media, run a remote job, and save the result.

An MIT-licensed, local stdio MCP connector for the videoworker video, audio and image processing API. Bring standard FFmpeg arguments; our workers run them. No local FFmpeg installation required.

Get started free · Hosted MCP · REST API · Releases

Choose your connection

Both use the same account and allowance. The connector is free software; hosted processing follows the current plans and limits. Free accounts receive a small monthly allowance. Check pricing for the Starter launch offer and its availability; a trial is not required to use Free.

Related MCP server: mcp-video-reader

Quick start

1. Install — no checkout or Git needed

Requires Python 3.12 or newer. Install the versioned release wheel:

python -m pip install "https://github.com/AzadKurt/videoworker-mcp/releases/download/v0.1.0/videoworker_mcp-0.1.0-py3-none-any.whl"
python -m videoworker_mcp --version

On Windows, use py -3.12 instead of python if needed. On macOS/Linux, your command may be python3. Use that same Python installation in your MCP config. Print its full path with:

python -c "import sys; print(sys.executable)"

Alternative with Git installed:

python -m pip install "git+https://github.com/AzadKurt/videoworker-mcp.git@v0.1.0"

This package is not on PyPI yet. pip install videoworker-mcp is not the command for this release.

2. Create your workspace and private key file

Sign in to your workspace. Under API keys, create a key with usage:read, files:write, jobs:read, jobs:write and outputs:read for all eight tools. Save it as plain text in a file accessible only to your user. On macOS/Linux: chmod 600 /absolute/path/to/key. On Windows, keep it in your user profile and restrict its file permissions to you.

Create uploads and downloads folders. Both must exist and use absolute paths. Keep only authorized media in uploads; keep the key file elsewhere. Never paste the key into a chat or a shared client config.

3. Add your client config

Replace the Python and file/folder paths with your own. Merge the entry into an existing config, preserving other servers. The values are paths, not secrets. Restart or reload your client after saving.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.videoworker]
command = "/absolute/path/to/python"
args = ["-m", "videoworker_mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 960

[mcp_servers.videoworker.env]
VIDEO_WORKER_API_KEY_FILE = "/absolute/path/to/videoworker.key"
VIDEO_WORKER_UPLOAD_ROOT = "/absolute/path/to/uploads"
VIDEO_WORKER_DOWNLOAD_ROOT = "/absolute/path/to/downloads"

Windows forward-slash paths work, e.g. C:/Users/YOU/media/uploads. Ready-to-edit: Windows / macOS and Linux. Keep the hosted connection named videoworker_remote if you also use it.

Claude Desktop

Open Settings → Developer → Edit Config and merge:

{
  "mcpServers": {
    "videoworker": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "videoworker_mcp"],
      "env": {
        "VIDEO_WORKER_API_KEY_FILE": "/absolute/path/to/videoworker.key",
        "VIDEO_WORKER_UPLOAD_ROOT": "/absolute/path/to/uploads",
        "VIDEO_WORKER_DOWNLOAD_ROOT": "/absolute/path/to/downloads"
      }
    }
  }
}

Ready-to-edit: Windows / macOS and Linux.

Cursor

Use the same JSON structure in ~/.cursor/mcp.json (global), or .cursor/mcp.json (project). Enable the server in Cursor's MCP settings. Ready-to-edit: Windows / macOS and Linux.

Examples follow documented stdio config formats. Real MCP SDK discovery is tested; this does not claim every desktop app/version was manually tested.

4. Try a small job

Put a small clip.mp4 in uploads and ask your agent:

Check my videoworker allowance first. I authorize uploading clip.mp4 from my configured uploads folder. Trim it to its first second and compress it as MP4. Create one job with a 10-second runtime limit. Keep its request_id for any retry, wait at least one second between status checks, and save the successful result as clip-small.mp4 in my downloads folder. Do not delete anything.

Flow: get_usage → upload_file → create_job → get_job → download_result. See example job arguments: replace the input file ID and generate a new UUID for each intended job.

Tools

Configuration and troubleshooting

VIDEO_WORKER_API_KEY is supported in private process environments and takes precedence over the file. Never put it in a shared config or command line. Custom origins require HTTPS, except explicit loopback HTTP for development.

• ENOENT / server not found: use the full Python path printed above, not a shell alias. GUI applications can have a different PATH.

• Configuration error: set the same variables in a terminal and run python -m videoworker_mcp --check. It validates local setup only, without API calls or credential/allowance verification. Help/version need no key.

• Unauthorized / forbidden: check your key, scopes and account in the dashboard. Never send credentials in a support message.

• File rejected: pass a flat name, not a path or URL. Local extensions: mp4, mp3, wav, webm, gif, png, jpg, jpeg, mkv, mov, ogg, flac. Linked folders and symlinks/junctions are rejected.

• Slow transfer: uploads/downloads can take up to 15 minutes per network operation. Configure suitable tool-call timeouts where supported. Closing a tool call does not cancel an accepted processing job.

Data and retries

The service enforces account ownership, allowance, file limits and expiry. The local process runs as your OS user; folder restrictions are application guards, not an operating-system sandbox. No local FFmpeg is bundled or needed.

Downloads never overwrite files or follow agent-supplied output URLs. Declared output sizes are bounded to 1 GiB; legacy metadata without a size has a 50-MiB fallback cap. Transfers stream instead of loading a full video into memory.

Keep one UUID request_id and identical arguments for job retries (48 hours). An uncertain response can still mean success. Uploads are not idempotent. Poll no faster than once per second and download before expiry. Cancellation/deletion are complete only after server confirmation. No billing/admin permissions needed.

Development

python -m pip install '.[dev]'
python -m pytest -q
python -m ruff check .
python -m ruff format --check .

Tests use tiny controlled HTTP fixtures and actual MCP SDK discovery. See release checks, dependency licenses and security reporting.

License and support

MIT for the connector; hosted processing and the private backend are separate. GitHub issues or info@videoworker.dev.

Config references: Codex, Claude Desktop, Cursor.