@ffmpeg-micro/mcp-server

A Model Context Protocol server that lets AI agents — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, and any other MCP-compatible client — create, monitor, and download video transcodes through the FFmpeg Micro REST API.

What it does

Exposes tools that map onto FFmpeg Micro's public API:

Blueprints

Blueprints are pre-built workflows behind POST /v1/blueprints/{slug}/runs. The tool descriptions document each blueprint's input fields. Notes:

• Most blueprints run on the FFmpeg lane and meter plan compute minutes (no tokens). Generative blueprints (product-ad) charge tokens; a 402 insufficient_tokens response means the account needs a token pack (dashboard).
• caption-video pauses in awaiting_review with the transcript (srt_text) so the agent can review/edit before rendering; resume with continue_blueprint_run.
• Multi-output blueprints (listing-kit, hook-variants) return an outputs array of {label, url} — prefer it over output_url when present.
• Output URLs are signed with a 10-minute TTL; re-fetch the run for fresh links.

Uploading a local file

The request_upload_url + confirm_upload pair lets an MCP host upload a local file to the FFmpeg Micro storage bucket without dealing with raw API keys or gs:// URLs:

1. Host calls request_upload_url with {filename, contentType, fileSize} → receives a short-lived presigned HTTPS URL.
2. Host PUTs the file bytes to that URL with the same Content-Type.
3. Host calls confirm_upload with {filename: <storage filename from step 1>, fileSize} → receives the final gs://... fileUrl.
4. Host passes that fileUrl to transcribe_audio / transcode_video / transcode_and_wait.

Quick start

Add this to your project's .mcp.json (or your MCP client's config):

{
  "mcpServers": {
    "ffmpeg-micro": {
      "type": "http",
      "url": "https://mcp.ffmpeg-micro.com"
    }
  }
}

That's it. The first time your AI tool connects, it will open a browser window for you to sign in with your FFmpeg Micro account via OAuth. After you approve, the token is cached and you won't be asked again.

No API keys to copy, no environment variables to set.

Authentication

OAuth (recommended)

The MCP server supports OAuth 2.1 with PKCE and dynamic client registration. Your MCP client handles the entire flow automatically:

1. Client discovers OAuth endpoints via /.well-known/oauth-authorization-server
2. Client registers itself dynamically
3. Browser opens for you to sign in and approve access
4. Token is exchanged and cached — subsequent connections are instant

This is the default when you use the config above with no headers or env block.

API key (alternative)

If you prefer to use an API key directly (e.g., for automation or CI), you can pass it as a Bearer token:

{
  "mcpServers": {
    "ffmpeg-micro": {
      "type": "http",
      "url": "https://mcp.ffmpeg-micro.com",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

Get your API key from the dashboard.

stdio (local install)

Runs the server as a local process using npx. Requires Node.js 22.14 or later.

{
  "mcpServers": {
    "ffmpeg-micro": {
      "command": "npx",
      "args": ["-y", "@ffmpeg-micro/mcp-server"],
      "env": {
        "FFMPEG_MICRO_API_KEY": "your_api_key_here"
      }
    }
  }
}

npx -y fetches the latest version each time. Any MCP client that supports stdio servers works with this config.

Compatible tools

The HTTP config (OAuth) works with any MCP client that supports streamable HTTP transport:

• Claude Code (CLI)
• Claude Desktop
• Cursor
• Windsurf
• VS Code (GitHub Copilot MCP)

The stdio config works with any MCP client that supports stdio transport.

Example prompts

Once connected, you can ask things like:

• "Transcode this video to 720p MP4 and give me the download URL when it's done."
• "Crop this landscape video to a square."
• "Add a text overlay saying 'Episode 12' to my video."
• "List my failed jobs from this week."
• "Cancel job b5f5a9c0-9e33-4e77-8a5b-6a0c2cd9c0b3."

Development

git clone https://github.com/javidjamae/ffmpeg-micro-mcp.git
cd ffmpeg-micro-mcp
./scripts/setup.sh

setup.sh installs dependencies, builds, and wires up the git hooks.

Point your MCP client at the local build to iterate:

{
  "mcpServers": {
    "ffmpeg-micro-dev": {
      "command": "node",
      "args": ["/absolute/path/to/ffmpeg-micro-mcp/dist/index.js"],
      "env": { "FFMPEG_MICRO_API_KEY": "…" }
    }
  }
}

The MCP Inspector is the fastest way to iterate on tool schemas and responses:

npx @modelcontextprotocol/inspector node dist/index.js

To run the HTTP server locally against a local API gateway:

FFMPEG_MICRO_API_URL=http://localhost:8081 npm run serve

Running integration tests locally

FFMPEG_MICRO_API_KEY=your_key npm run test:integration

Integration tests hit the real FFmpeg Micro production API. They are read-only (no jobs are created).

Smoke-testing the upload tools end-to-end

Unit tests use a mocked fetch, so they prove tool registration + Zod schemas + URL paths but not that the wire shapes match what the gateway actually returns. Two smoke scripts exercise the full request_upload_url → PUT → confirm_upload flow against a real MCP server using a real API key. Run them in order — stdio first (fastest signal), then a deployed HTTP server before/after merge:

# 1. stdio (local dist build) — spawns dist/index.js as a subprocess
npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-upload-stdio.mjs <local-file>

# 2. HTTP (any deployed server — local `npm run serve`, Vercel preview, or prod)
FFMPEG_MICRO_API_KEY=your_key MCP_URL=https://mcp.ffmpeg-micro.com/ \
  node scripts/smoke-upload-http.mjs <local-file>

Both scripts hit the production API by default and consume billable minutes (the stdio script chains into transcribe_audio for an end-to-end check). Pass a small file like 15-second.mp3 to keep the cost negligible.

A third script smoke-tests the blueprint tools (run_blueprint + get_blueprint_run polled to completion on resize-format, then run_blueprint_and_wait on hook-variants to exercise multi-output). It uses FFmpeg-lane blueprints only, so it consumes plan compute minutes but no tokens:

npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-blueprints-stdio.mjs

Hitting protection-protected Vercel previews

Vercel preview deployments are gated by Deployment Protection by default. To exercise the HTTP smoke script against a preview URL, generate a Protection-Bypass-for-Automation token in the project's Vercel settings and pass it via VERCEL_BYPASS:

FFMPEG_MICRO_API_KEY=your_key \
  MCP_URL=https://your-preview.vercel.app/ \
  VERCEL_BYPASS=your_bypass_token \
  node scripts/smoke-upload-http.mjs <local-file>

The script sends the token as the x-vercel-protection-bypass header on every request. It does not send x-vercel-set-bypass-cookie: true — that variant triggers a 307 cookie-setting redirect on POST that the MCP SDK's StreamableHTTPClientTransport does not follow, so the request fails. The header alone returns 200 directly without the redirect dance.

Release process

Releases are published to npm via trusted publishing and to the MCP Registry as com.ffmpeg-micro/mcp-server, authenticated via an Ed25519 DNS TXT record on ffmpeg-micro.com. The corresponding private key lives in the MCP_PRIVATE_KEY GitHub Actions secret. The npm side uses OIDC trusted publishing, so no npm token is stored.