# videoctx MCP server

> Enables AI agents to index videos locally and query them via a text layer and on-demand frame retrieval.

- Repository: https://github.com/dunfred/videoctx
- Page: https://hostedmcp.org/servers/dunfred/videoctx
- Transport: stdio
- Stars: 1
- License: Apache-2.0
- Latest version: 0.1.5

## Install

### Claude Code

```sh
claude mcp add videoctx -- uvx 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"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"videoctx","type":"stdio","command":"uvx","args":["videoctx"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

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

### Codex

```sh
codex mcp add videoctx -- uvx videoctx
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.videoctx]
command = "uvx"
args = ["videoctx"]
```

### Gemini CLI

```sh
gemini mcp add -s user videoctx uvx -- videoctx
```

### Gemini settings.json (`~/.gemini/settings.json`)

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

## Tools (6)

- `index_video`: Index a video file for querying (shots, keyframes, speech transcript). Runs locally; takes roughly 10-20% of the video's duration. Idempotent - returns immediately if the video is already indexed. The other tools auto-index too, so calling this first is only needed to control when the wait happens.
- `video_overview`: The cheap text layer of a video: shot list with timestamps and visual captions (when present), interleaved with the speech transcript. Read this before fetching any frames: it answers most questions by itself.
- `survey_video`: One small thumbnail per shot across the whole video (subsampled to at most 24), each labeled with its timestamp. Cheap visual sweep for locating the relevant moment before zooming in with get_frames.
- `get_frames`: Frames evenly spaced across [start_s, end_s]. Frames are expensive: use the narrowest range the question allows, and raise max_frames (up to 8) only when a sparse sample missed the moment. Set detail='high' (2x resolution, ~4x token cost) when small text, colors, patterns, or fine object details matter.
- `find_moments`: Semantic visual search: find the moments that best match a natural language description (e.g. 'a red car at night'), using local CLIP embeddings. Returns the top matches as timestamped thumbnails: use the timestamps to zoom in with get_frames. Requires embeddings built once with `videoctx embed <index>`; cheaper and more targeted than survey_video when you know what you are looking for.
- `transcript_search`: Case-insensitive search over the transcript. Returns matching segments with surrounding context and timestamps: use the timestamps to target get_frames.

## FAQ

### What tools are required to run videoctx?

You will need Python, ffmpeg, and an Anthropic API key for question-answering capabilities.

### How does the MCP server handle video data?

The server provides tools for overview, surveying shots, fetching specific frames, searching transcripts, and semantic visual search without making its own model calls.
