# FFmpeg MCP Server

MCP server providing FFmpeg video processing via base64 I/O. Stateless, portable, zero external dependencies.

## Tools

### get_ffmpeg_version

Returns FFmpeg version information.

### resize_video

Resize video to standard resolutions (360p, 480p, 720p, 1080p). Outputs H.264/AAC.

**Parameters:**

- `videoBase64` (string): Base64 encoded video
- `resolutions` (array): Target resolutions
- `outputFormat` (string, optional): mp4 or webm (default: mp4)

**Returns:** Base64 encoded video for each resolution

### extract_audio

Extract audio track from video.

**Parameters:**

- `videoBase64` (string): Base64 encoded video
- `format` (string): mp3, aac, wav, or ogg

**Returns:** Base64 encoded audio

### get_video_info

Inspect video metadata: format, duration, bitrate, resolution, codecs, streams.

**Parameters:**

- `videoBase64` (string): Base64 encoded video

**Returns:** Formatted metadata

## Design

**Base64 I/O:** All inputs and outputs are base64 encoded. No file paths, S3 URLs, or database storage.

**Why:**

- Stateless: No persistent storage, cleanup, or orphaned files
- Portable: Works in any Node.js environment
- Simple: Single request/response cycle

**Constraints:**

- Payload limits: ~4-6 MB depending on runtime
- Best for: Thumbnails, previews, short clips, audio extraction
- Not for: Feature films, 4K processing

**Processing flow:**

1. Decode base64 input → temp file
2. Execute FFmpeg
3. Read output → buffer
4. Delete temp files
5. Encode buffer → base64

## Installation

FFmpeg binaries install automatically via `ffmpeg-static` and `@ffprobe-installer/ffprobe`.

```bash
npm install @windsornguyen/ffmpeg-mcp
```

## Configuration

### Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ffmpeg": {
      "command": "npx",
      "args": ["-y", "@windsornguyen/ffmpeg-mcp"]
    }
  }
}
```

### VS Code

`.vscode/mcp.json`:

```json
{
  "servers": {
    "ffmpeg": {
      "command": "npx",
      "args": ["-y", "@windsornguyen/ffmpeg-mcp"]
    }
  }
}
```

## Development

```bash
# Install dependencies
bun install

# Build
bun run build

# Test
bun test

# Run STDIO transport
bun run dev:stdio

# Run HTTP transport
bun run dev:shttp
```

### Environment Variables

- `PORT`: HTTP server port (default: 3002)
- `NODE_ENV`: development | production

## Testing

```bash
# Run all tests
bun test

# Run with output artifacts (kept in tests/output/)
bun test --keep-artifacts

# Single test file
bun test tests/ffmpeg.test.ts
```

Tests verify base64 round-trip encoding, resolution accuracy, and codec compliance. Output artifacts saved to `tests/output/` when `--keep-artifacts` is set.

## Architecture

- **Client** (`src/client.ts`): FFmpeg execution with base64 I/O
- **Tools** (`src/tools/ffmpeg.ts`): MCP tool definitions
- **Server** (`src/server.ts`): Request routing
- **Transport** (`src/transport/`): STDIO and HTTP support

## License

MIT License. See LICENSE file for details.