# Video Understanding MCP

> Video Understanding MCP is an MCP server for design and media. Ask questions about a video file or TikTok, YouTube or X link via a video-capable model. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Platforms:** CLI, macOS, Linux, Windows
- **Repository:** https://github.com/granitebps/video-understanding-mcp
- **MCP Registry name:** io.github.granitebps/video-understanding-mcp
- **Categories:** [design and media](https://ai-powered.com/categories/design-and-media), [AI models and LLM tooling](https://ai-powered.com/categories/ai-and-llm)
- **Listing updated:** 2026-11-18

## About

You supply a page URL, a direct media URL or an allowed local file plus a question; the server downloads and shrinks the video with ffmpeg, sends it to an OpenAI-compatible chat endpoint whose model accepts video, and returns a structured answer. The result holds an answer, a summary, speech with language and transcript, on-screen text, a timeline of moments and analysis metadata including usage and warnings.

Endpoints disagree on how a video is attached, so VIDEO_PART_FORMAT selects video_url, image_url (default), file or input_file. To avoid answers invented from nothing, it sends a parallel prompt without the video and compares prompt-token usage; if the endpoint evidently ignored the video, the call fails with MEDIA_NOT_PROCESSED. That doubles requests and can be switched off.

Local files are refused unless VIDEO_ALLOWED_DIRS is set. It needs Node.js 22.21 or newer and ffmpeg, plus yt-dlp for TikTok or YouTube page links, and the default analysed range is 300 seconds.

## Features

- **Structured answers:** Returns answer, summary, speech transcript, on-screen text and a timeline.
- **Many sources:** Accepts page URLs, direct media URLs with headers, or allowed local files.
- **Endpoint formats:** Four request formats cover different OpenAI-compatible gateways.
- **Ignored-video check:** Fails with MEDIA_NOT_PROCESSED if the endpoint did not use the video.
- **Range and limits:** Analyse a start and end range within configurable duration and upload limits.

## Good for

- Summarise a TikTok or YouTube video
- Pull on-screen text and timestamps from a clip
- Transcribe speech in a short video
- Review a local screen recording against a question
- Analyse a short range of a workout video

## Install

### Claude Code (Terminal)

```sh
claude mcp add video-understanding-mcp --env VIDEO_BASE_URL='<VIDEO_BASE_URL>' --env VIDEO_MODEL='<VIDEO_MODEL>' --env VIDEO_API_KEY='<VIDEO_API_KEY>' --env VIDEO_EXTRA_HEADERS='<VIDEO_EXTRA_HEADERS>' -- npx -y @granitebps/video-understanding-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "video-understanding-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@granitebps/video-understanding-mcp"
      ],
      "env": {
        "VIDEO_BASE_URL": "<VIDEO_BASE_URL>",
        "VIDEO_MODEL": "<VIDEO_MODEL>",
        "VIDEO_API_KEY": "<VIDEO_API_KEY>",
        "VIDEO_EXTRA_HEADERS": "<VIDEO_EXTRA_HEADERS>"
      }
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "video-understanding-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@granitebps/video-understanding-mcp"
      ],
      "env": {
        "VIDEO_BASE_URL": "<VIDEO_BASE_URL>",
        "VIDEO_MODEL": "<VIDEO_MODEL>",
        "VIDEO_API_KEY": "<VIDEO_API_KEY>",
        "VIDEO_EXTRA_HEADERS": "<VIDEO_EXTRA_HEADERS>"
      }
    }
  }
}
```

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

```json
{
  "servers": {
    "video-understanding-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@granitebps/video-understanding-mcp"
      ],
      "env": {
        "VIDEO_BASE_URL": "<VIDEO_BASE_URL>",
        "VIDEO_MODEL": "<VIDEO_MODEL>",
        "VIDEO_API_KEY": "<VIDEO_API_KEY>",
        "VIDEO_EXTRA_HEADERS": "<VIDEO_EXTRA_HEADERS>"
      }
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "video-understanding-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@granitebps/video-understanding-mcp"
      ],
      "env": {
        "VIDEO_BASE_URL": "<VIDEO_BASE_URL>",
        "VIDEO_MODEL": "<VIDEO_MODEL>",
        "VIDEO_API_KEY": "<VIDEO_API_KEY>",
        "VIDEO_EXTRA_HEADERS": "<VIDEO_EXTRA_HEADERS>"
      }
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "video-understanding-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@granitebps/video-understanding-mcp"
      ],
      "env": {
        "VIDEO_BASE_URL": "<VIDEO_BASE_URL>",
        "VIDEO_MODEL": "<VIDEO_MODEL>",
        "VIDEO_API_KEY": "<VIDEO_API_KEY>",
        "VIDEO_EXTRA_HEADERS": "<VIDEO_EXTRA_HEADERS>"
      }
    }
  }
}
```

## Tools

- `understand_video`: Analyses a video from a URL or local path and answers a question about it.
- `get_server_info`: Shows version, endpoint host, model, limits and tool availability.

## FAQ

### What does it need?

Node.js 22.21.0 or newer, ffmpeg with ffprobe, an OpenAI-compatible endpoint with a video-capable model, and yt-dlp for page URLs.

### Can it read local files?

Only inside directories listed in VIDEO_ALLOWED_DIRS; local files are refused when it is unset.

### What is the default maximum length?

300 seconds of analysed range, configurable up to 7200.

### How do I check setup?

Call the get_server_info tool to see versions, limits and whether ffmpeg and yt-dlp are found.

### How do I add Video Understanding MCP to Claude Code?

Run this command in your terminal: claude mcp add video-understanding-mcp --env VIDEO_BASE_URL='<VIDEO_BASE_URL>' --env VIDEO_MODEL='<VIDEO_MODEL>' --env VIDEO_API_KEY='<VIDEO_API_KEY>' --env VIDEO_EXTRA_HEADERS='<VIDEO_EXTRA_HEADERS>' -- npx -y @granitebps/video-understanding-mcp

### What are the best alternatives to Video Understanding MCP?

The closest alternatives to Video Understanding MCP are HyperFrames by HeyGen, headroom, omniget, next-ai-draw-io and mcp-for-blender.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [HyperFrames by HeyGen](https://ai-powered.com/mcp/hyperframes-by-heygen): HyperFrames by HeyGen is a freemium MCP server for design and media.
- [headroom](https://ai-powered.com/mcp/headroom-3): headroom is an open-source MCP server for ai models and llm tooling.
- [omniget](https://ai-powered.com/mcp/omniget): omniget is an open-source MCP server for ai models and llm tooling.
- [next-ai-draw-io](https://ai-powered.com/mcp/next-ai-draw-io-2): next-ai-draw-io is an open-source MCP server for ai models and llm tooling.
- [mcp-for-blender](https://ai-powered.com/mcp/mcp-for-blender): mcp-for-blender is an open-source 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.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [unity-mcp](https://ai-powered.com/mcp/unity-mcp-2): unity-mcp is an open-source MCP server for ai models and llm tooling.

---
Source: https://ai-powered.com/mcp/video-understanding-mcp
