# videoctx

> videoctx is a free MCP server for files and documents. Read videos through a local text index, with frames fetched only when needed. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** CLI, macOS, Linux, Windows
- **Repository:** https://github.com/dunfred/videoctx
- **MCP Registry name:** io.github.dunfred/videoctx
- **Categories:** [files and documents](https://ai-powered.com/categories/files-and-documents), [AI models and LLM tooling](https://ai-powered.com/categories/ai-and-llm)
- **Listing updated:** 2026-11-18

## About

videoctx builds an open, portable index of a video, stored as a .vctx folder of JSON and JPEG, using only local tools: ffmpeg keyframes, PySceneDetect shot boundaries, faster-whisper transcripts and optional one-line captions. A question is answered from the text layer first, and individual frames are fetched only when it needs pixels.

The README argues this avoids re-tokenizing an hour of video on every question, quoting roughly 250 to 350 thousand tokens, and reports about two cents for a follow-up on an hour-long video. Its Video-MME results are described with caveats: on short videos the latest version scored 84.7 percent, and medium-length videos are called its weakest case.

The MCP server makes no model calls and needs no key; the calling agent reads the text and frames itself. A command-line ask feature uses the Anthropic API. It is aimed at developers comfortable with Python and ffmpeg.

## Features

- **Local indexing:** Indexes video offline with free tools.
- **Open format:** Plain JSON and JPEG .vctx folders.
- **Text-first queries:** Answers from transcript and captions before fetching frames.
- **On-demand frames:** Pulls specific frames for visual questions.
- **Semantic moment search:** Finds visual moments after a one-time embed step.
- **Published benchmarks:** Shows accuracy and cost with caveats.

## Good for

- Summarise a lecture with timestamps
- Find action items in a recorded meeting
- Locate an error dialog in a screen recording
- Index a talk archive once and query it repeatedly

## Install

### Claude Code (Terminal)

```sh
claude mcp add videoctx -- uvx videoctx
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "videoctx": {
      "command": "uvx",
      "args": [
        "videoctx"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "videoctx": {
      "command": "uvx",
      "args": [
        "videoctx"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "videoctx": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "videoctx"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "videoctx": {
      "command": "uvx",
      "args": [
        "videoctx"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "videoctx": {
      "command": "uvx",
      "args": [
        "videoctx"
      ]
    }
  }
}
```

## Tools

- `video_overview`: Cheap text-layer overview of a video
- `survey_video`: One thumbnail per shot
- `get_frames`: Fetches frames between two times at a chosen detail level
- `transcript_search`: Searches the transcript
- `find_moments`: Semantic visual search, needs an embed step
- `index_video`: Indexes a video

## FAQ

### Does indexing cost anything?

The README says indexing is local and free.

### Does the MCP server need a key?

No, it makes no model calls.

### What do I need installed?

Python and ffmpeg.

### What is the cost of follow-up questions?

About $0.02 for an hour-long video, per the README.

### Is videoctx free?

Yes. videoctx is free to use.

### How do I add videoctx to Claude Code?

Run this command in your terminal: claude mcp add videoctx -- uvx videoctx

### What are the best alternatives to videoctx?

The closest alternatives to videoctx are headroom, omniget, next-ai-draw-io, mcp-for-blender and Claude Code Ultimate Guide.

## Where this comes from

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

## Alternatives

- [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.
- [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.
- [fastapi_mcp](https://ai-powered.com/mcp/fastapi-mcp): fastapi_mcp is an open-source MCP server for ai models and llm tooling.
- [tyk](https://ai-powered.com/mcp/tyk): tyk is an open-source MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/videoctx
