# Frame Lens

> Frame Lens is an open-source MCP server for design and media. Local MCP server that measures cuts, easing, palette and beats in video for agents. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Windows, Linux
- **Website:** https://makkov-design.github.io/framelens/
- **Repository:** https://github.com/makkov-design/framelens
- **MCP Registry name:** io.github.Makkov-design/framelens
- **Categories:** design and media
- **Listing updated:** 2026-11-14

## About

Most agents that watch video get a few stills or captions and guess at motion. Frame Lens returns numbers instead: cuts to the exact frame, each move with its duration and fitted easing curve, an OKLab palette per shot, loudness, tempo and beat grid, and transcripts with word timings. Every figure is tagged as measured, derived or inferred.

In its own test it animated a square in HyperFrames, measured it back, and recovered the curve within 0.18 px; the README also reports 33 of 33 cuts found on the exact frame in synthetic clips at 24, 30 and 60 fps. Live websites, Lottie, Rive and Figma are read from their own data rather than from pixels. The tools named include track, export and compare: export writes a measured curve into CSS, Remotion, HyperFrames, After Effects or Lottie, and compare checks a render against the reference.

It is free and MIT licensed, runs locally on Node 20 with ffmpeg and yt-dlp fetched on first use with checksums, and needs no API key except for the optional Gemini YouTube tools.

## Features

- **Frame-exact cuts:** Finds cuts, fades and dissolves with their frame positions.
- **Easing curves:** Fits cubic-bezier or spring values to each measured move.
- **Audio analysis:** Reports loudness, tempo, beat grid and word-timed transcripts.
- **Five export targets:** Writes starter projects for CSS, Remotion, HyperFrames, After Effects and Lottie.
- **Token-saving frames:** Sends an overview sheet first, then dense frames only around changes.

## Good for

- Rebuild a promo video's motion in Remotion
- Turn a tutorial into a step-by-step guide with a frame per screen
- Find where in a long talk a topic is discussed
- Check whether cuts land on the beat
- Compare a render against a reference animation

## Install

### Claude Code (Terminal)

```sh
claude mcp add framelens --env GEMINI_API_KEY='<GEMINI_API_KEY>' -- npx -y framelens
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "framelens": {
      "command": "npx",
      "args": [
        "-y",
        "framelens"
      ],
      "env": {
        "GEMINI_API_KEY": "<GEMINI_API_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "framelens": {
      "command": "npx",
      "args": [
        "-y",
        "framelens"
      ],
      "env": {
        "GEMINI_API_KEY": "<GEMINI_API_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "framelens": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "framelens"
      ],
      "env": {
        "GEMINI_API_KEY": "<GEMINI_API_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "framelens": {
      "command": "npx",
      "args": [
        "-y",
        "framelens"
      ],
      "env": {
        "GEMINI_API_KEY": "<GEMINI_API_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "framelens": {
      "command": "npx",
      "args": [
        "-y",
        "framelens"
      ],
      "env": {
        "GEMINI_API_KEY": "<GEMINI_API_KEY>"
      }
    }
  }
}
```

## Tools

- `track`: Measures moves and fits easing curves from a video.
- `export`: Writes a measured curve into CSS, Remotion, HyperFrames, After Effects or Lottie.
- `compare`: Checks your render against the reference.

## FAQ

### Does it need an API key?

No, except the optional Gemini key for the Gemini YouTube tools.

### What does it need installed?

Node.js 20 and ffmpeg; yt-dlp is downloaded and checksum-verified on first use.

### Which sources can it read?

Local video files, YouTube and many other sites, live websites, Lottie, Rive and Figma.

### What is the licence?

MIT, according to the site.

### Is Frame Lens free?

Yes. Frame Lens is open source, so you can use and self-host it for free.

### How do I add Frame Lens to Claude Code?

Run this command in your terminal: claude mcp add framelens --env GEMINI_API_KEY='<GEMINI_API_KEY>' -- npx -y framelens

### What are the best alternatives to Frame Lens?

The closest alternatives to Frame Lens are HyperFrames by HeyGen, ffmpeg-skill, AvatarSay — Fictional Character & Talking Video MCP, ChartAnt and VfxSmith.

## Alternatives

- [HyperFrames by HeyGen](https://ai-powered.com/mcp/hyperframes-by-heygen): HyperFrames by HeyGen is a freemium MCP server for design and media.
- [ffmpeg-skill](https://ai-powered.com/mcp/ffmpeg-skill): ffmpeg-skill is an open-source MCP server for design and media.
- [AvatarSay — Fictional Character & Talking Video MCP](https://ai-powered.com/mcp/avatarsay-fictional-character-and-talking-video-mcp): AvatarSay — Fictional Character & Talking Video MCP is a freemium MCP server for design and media.
- [ChartAnt](https://ai-powered.com/mcp/chartant): ChartAnt is a freemium MCP server for design and media.
- [VfxSmith](https://ai-powered.com/mcp/vfxsmith): VfxSmith is a freemium MCP server for design and media.
- [CalderFlow](https://ai-powered.com/mcp/calderflow): CalderFlow is a free MCP server for design and media.
- [Eikino](https://ai-powered.com/mcp/eikino): Eikino is a freemium MCP server for security.
- [Hourlore](https://ai-powered.com/mcp/hourlore): Hourlore is a freemium MCP server for design and media.

---
Source: https://ai-powered.com/mcp/frame-lens
