Videoworker MCP Server

videoworker MCP

Give your AI agent a media workflow: upload, pick a preset, save the result.

An MIT-licensed, local stdio MCP connector for the videoworker video, audio and image processing API. Use versioned presets for everyday exports or standard FFmpeg arguments for custom edits. Our workers run the processing; no local FFmpeg installation required.

Get started free · Hosted MCP · REST API · Releases · Listed on Glama

What can your agent do?

Subtitle presets take two inputs: the video, then your own .srt or .vtt file (up to 2 MiB). They do not transcribe or translate.

Discover parameters and the required input count with list_presets, then use run_preset with your uploaded file IDs in the displayed order and an explicit version. For multi-file edits, overlays or your own filters, create_job accepts custom FFmpeg arguments. Track, cancel and download both kinds of job through the same tools and account allowance.

Signed job webhooks notify your own HTTPS endpoint when a job finishes; they are live on videoworker.dev. Selecting an endpoint per job works through hosted MCP, REST and this source checkout (guide, with a durable receiver example); the published v0.2.0 wheel does not include that argument yet. Preset availability always comes from the server catalog, so check list_presets rather than assuming a preset exists.

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.

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.2.0/videoworker_mcp-0.2.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.2.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 ten 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 and list the presets first. I authorize uploading clip.mp4 from my configured uploads folder. Use web-mp4 version 1 to export the first second as MP4 with max_width 640 and a 10-second processing maximum. Create one job. Keep its request_id for retries, wait at least one second between status checks, and save the successful result in my downloads folder. Do not delete anything.

Flow: get_usage → list_presets → upload_file → run_preset → get_job → download_result. See preset arguments: replace the input file ID and generate a new UUID for each intended job. Prefer raw commands? Use create_job with these example job arguments.

More than one input

Workflow recipes cover joining clips, adding an image/logo, and replacing a soundtrack. Each includes input order, behavior notes and a ready-to-edit MCP JSON file. The same recipes are displayed on the website with copy buttons for REST and MCP.

Versioned presets

On a server that supports GET /v1/presets, use list_presets to discover validated parameters, pinned versions and output filenames. Then call run_preset with an uploaded file ID, explicit version, parameters, processing maximum and a chosen UUID. Example MCP arguments trim and resize video into H.264/AAC MP4. Other catalog entries extract MP3, produce a JPEG thumbnail or render a short GIF.

The same ordinary job quota, ownership and storage rules apply. The timeout reserves a processing maximum, not the clip duration. Poll get_job at most once per second and download before expiry. Use the identical request and UUID for retries within 48 hours; never automatically resubmit a lost reply. Defaults and encoding behavior are pinned by version. Smaller output size is not guaranteed.

Version 0.2.0 adds these tools and requires a server with preset support. presets_unsupported means the server has no catalog; presets_unsupported also identifies a missing execution route; preset_not_found identifies an unknown ID/version and input_unavailable means the owned upload is missing or expired. Unknown 404 shapes remain preset_unavailable. No case silently falls back to another job. Listing presets first checks the same key against the owned jobs-read endpoint, since the REST metadata catalog itself is intentionally public.

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.