ffmpeg-micro-mcp

# @ffmpeg-micro/mcp-server

[![npm version](https://img.shields.io/npm/v/@ffmpeg-micro/mcp-server.svg)](https://www.npmjs.com/package/@ffmpeg-micro/mcp-server)
[![CI](https://github.com/ffmpeg-micro/ffmpeg-micro-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ffmpeg-micro/ffmpeg-micro-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io) 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](https://ffmpeg-micro.com) REST API.

## What it does

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

| Tool | What it does |
| --- | --- |
| `transcode_video` | Create a transcode job from one or more input videos (`gs://` or `https://`). Supports quality/resolution presets and raw FFmpeg options. |
| `get_transcode` | Fetch the current state of a single job. |
| `list_transcodes` | List jobs with optional `status`, `page`, `limit`, `since`, `until` filters. |
| `cancel_transcode` | Cancel a pending or processing job. |
| `get_download_url` | Generate a 10-minute signed HTTPS URL for a completed job's output file. |
| `transcode_and_wait` | Convenience: create a job, poll until it finishes, return the signed download URL in one call. |
| `request_upload_url` | Step 1 of the direct-upload flow. Returns a presigned HTTPS URL that the host PUTs the file bytes to. |
| `confirm_upload` | Step 2 of the direct-upload flow. Returns the final `gs://` URL plus probe metadata, ready to use as a transcode/transcribe input. |
| `run_blueprint` | Start a blueprint run — a pre-built video workflow (captioning, resizing, watermarking, ads, and more). |
| `get_blueprint_run` | Fetch a blueprint run's status, step, and output URLs (multi-output blueprints return labeled `outputs`). |
| `run_blueprint_and_wait` | Convenience: start a blueprint run and poll until it completes, fails, or pauses for transcript review. |
| `continue_blueprint_run` | Resume a `caption-video` run paused in `awaiting_review` by submitting the approved SRT transcript. |

### 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](https://www.ffmpeg-micro.com/dashboard/blueprints)).
- `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):

```json
{
  "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](https://ffmpeg-micro.com) 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:

```json
{
  "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](https://www.ffmpeg-micro.com/dashboard/api-keys).

### stdio (local install)

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

```json
{
  "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

```bash
git clone https://github.com/ffmpeg-micro/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:

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

The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is the fastest way to iterate on tool schemas and responses:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

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

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

### Running integration tests locally

```bash
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:

```bash
# 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:

```bash
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`:

```bash
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](https://www.npmjs.com/package/@ffmpeg-micro/mcp-server) via [trusted publishing](https://docs.npmjs.com/trusted-publishers/) and to the [MCP Registry](https://registry.modelcontextprotocol.io) 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.

Rele