Skip to content
MCP server

videoctx

Read videos through a local text index, with frames fetched only when needed

Runs locallyStatus and history
Install
Pricing
Free
Platforms
CLI, macOS, Linux
Runs
Locally
Version
0.1.5
Listing updated
today

Similar MCP servers

About videoctx

videoctx is a free MCP server for files and documents. It runs locally on your machine and is started by your AI client.

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.

Install

Run in a terminal

claude mcp add videoctx -- uvx videoctx

Add to claude_desktop_config.json

{
  "mcpServers": {
    "videoctx": {
      "command": "uvx",
      "args": [
        "videoctx"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "videoctx": {
      "command": "uvx",
      "args": [
        "videoctx"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

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

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Using several servers? Build one config file with the MCP config generator.

Tools this server provides (6)

Taken from the project documentation; the running server may differ.

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

What it does

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

Pricing

Free

Indexing is local; the optional ask command uses your Anthropic API key

videoctx 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.

How AIPoweredBot checks servers