# claudeclip

[![CI](https://github.com/gulkoa/claudeclip/actions/workflows/ci.yml/badge.svg)](https://github.com/gulkoa/claudeclip/actions/workflows/ci.yml)

A local [MCP](https://modelcontextprotocol.io) server that lets Claude edit videos on your machine, powered by ffmpeg. Works with Claude Cowork, Claude Desktop, Claude Code, and any other MCP client, on Windows, macOS, and Linux — ffmpeg is bundled automatically if you don't have it.

Ask things like *"trim the first 30 seconds off intro.mp4 and turn the best part into a GIF"* — Claude inspects the file, picks the right tools, and writes the results next to your originals.

## Tools

| Tool | What it does |
| --- | --- |
| `get_video_info` | Duration, resolution, fps, codecs, bitrate, file size |
| `sample_frames` | Contact sheet of timestamped frames — lets Claude *see* the video before editing |
| `detect_scenes` | Timestamps of cuts/shot changes, ready to feed into trims |
| `detect_silence` | Silent stretches plus the non-silent segments to keep (cut dead air) |
| `trim_video` | Cut to a time range — frame-accurate re-encode, or instant `fast_copy` |
| `concat_videos` | Join clips in order, with hard cuts or crossfades; mixed resolutions/frame rates are normalized automatically |
| `convert_video` | Re-encode to mp4 / webm / mov / mkv with a quality preset |
| `resize_video` | Scale by width, height, or percentage (aspect ratio preserved) |
| `crop_video` | Crop a rectangle out of the frame |
| `compress_video` | Shrink to an approximate target size in MB, or general-purpose compression |
| `change_speed` | 0.25x–4x playback speed, audio pitch preserved |
| `rotate_video` | Rotate 90/180/270° and/or mirror horizontally/vertically |
| `add_fade` | Fade in from black / out to black, video and audio |
| `reverse_video` | Play backwards (best for short clips) |
| `loop_video` | Repeat N times or until a target duration, no re-encode |
| `adjust_colors` | Brightness, contrast, saturation (saturation 0 = black & white) |
| `stack_videos` | Side-by-side, vertical, or grid comparison layouts |
| `picture_in_picture` | Overlay a video in a corner (webcam/reaction style) |
| `video_from_images` | Slideshow from images, optional soundtrack |
| `create_gif` | Palette-optimized animated GIF from a clip |
| `extract_frame` | Save a still frame as jpg/png (thumbnails, covers) |
| `extract_audio` | Audio track out to mp3 / wav / m4a / flac |
| `remove_audio` | Strip audio without re-encoding |
| `replace_audio` | Swap in music or a voiceover, optionally looped to fit |
| `adjust_volume` | Louder/quieter by a multiplier |
| `normalize_audio` | EBU R128 loudness normalization (podcast/social levels) |
| `add_text_overlay` | Captions/titles: position presets, color, background box, show/hide times |
| `add_watermark` | Image/logo overlay with size and opacity |
| `draw_box` | Rectangle outline or filled box for highlighting/redacting, with time window |
| `blur_region` | Blur or pixelate a region (faces, plates, names), with time window |
| `burn_subtitles` | Permanently render an .srt/.ass subtitle file onto the video |

**Safe by default:** tools never overwrite files. Without an explicit `output_path`, results land next to the input as `name_trimmed.mp4`, `name_clip.gif`, etc., and name collisions get a numeric counter.

## Requirements

- [Node.js](https://nodejs.org) 18+
- ffmpeg — **required, and installed for you**: `npm install` always fetches ffmpeg/ffprobe binaries for your platform (Windows, macOS Intel/Apple Silicon, Linux), so the server works out of the box. If a system [ffmpeg](https://ffmpeg.org/download.html) is present it is preferred (newer and faster); the lookup order is `FFMPEG_PATH`/`FFPROBE_PATH` env vars → common install locations (incl. `~/ffmpeg`, `C:\ffmpeg\bin`, Homebrew) → `PATH` → bundled.

## Install

### Option 1 — npx (easiest)

No download at all — with [Node.js](https://nodejs.org) 18+ installed, just use `npx` in your Claude config (first run fetches everything, including ffmpeg):

```json
{
  "mcpServers": {
    "claudeclip": {
      "command": "npx",
      "args": ["-y", "claudeclip"]
    }
  }
}
```

Or for Claude Code: `claude mcp add claudeclip -- npx -y claudeclip`

### Option 2 — download a release

Grab the zip for your platform from the [latest release](https://github.com/gulkoa/claudeclip/releases/latest), unzip it somewhere permanent, and point your Claude config at `dist/index.js` inside it (see below). The zip is self-contained — Node.js 18+ is the only requirement, ffmpeg is included.

### Option 3 — from source

```sh
git clone https://github.com/gulkoa/claudeclip.git
cd claudeclip
npm install
npm run build
```

## Connect to Claude

### Claude Cowork / Claude Desktop

Add the server to your Claude config file:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "claudeclip": {
      "command": "node",
      "args": ["/absolute/path/to/claudeclip/dist/index.js"]
    }
  }
}
```

Restart the Claude app; the tools appear under the `claudeclip` server. (If `node` isn't found, use the full path to the Node executable as `command`.)

### Claude Code

```sh
claude mcp add claudeclip -- node /absolute/path/to/claudeclip/dist/index.js
```

## Example prompts

- "How long is `C:\Videos\demo.mp4` and what resolution is it?"
- "Cut `talk.mp4` from 12:30 to 14:00 and compress the result to about 25 MB"
- "Join these three clips and add my `logo.png` as a watermark in the bottom right"
- "Make a 5-second GIF of the goal at 1:23, 480px wide"
- "Replace the audio in `timelapse.mp4` with `song.mp3`, looped to fit"
- "Burn `episode1.srt` into the video and caption the intro with the show title"
- "Look at what's in `raw.mp4`, then cut it into separate scenes"
- "Remove the dead air from this recording and normalize the audio"
- "Put `screen.mp4` and `webcam.mp4` side by side" / "webcam in the corner"
- "Pixelate the license plate at the top right from 0:12 to 0:31"

## Notes

- Text overlays render with a system font (Arial/Segoe UI on Windows, Helvetica on macOS, DejaVu on Linux). Arbitrary text is safe — it's passed to ffmpeg via a temp file, so quotes, `%`, `:` and friends can't break the filter graph.
- Encoding defaults favor compatibility: H.264 + AAC in mp4 with `+faststart`, VP9 + Opus for webm.
- Long jobs time out after 15 minutes.

## Development

```sh
npm run build          # compile TypeScript to dist/
node test/smoke.mjs    # end-to-end test: spawns the server over stdio,
                       # generates test media with ffmpeg, exercises every tool
```

## License

MIT