How to add video analysis to Claude, Cursor, and any MCP-compatible tool

Claude can read PDFs. Cursor can navigate your codebase. But neither of them can watch a video and tell you what's in it.

That changes with one command:

pip install vidcontext-mcp

The VidContext MCP server gives any MCP-compatible AI tool the ability to analyze video files. Upload a video, pick a mode, get structured text output back. The AI tool sees the results as regular text context it can reason about.

This guide walks through setup for Claude Desktop, Claude Code, and Cursor. The whole process takes about 2 minutes.

What you get

Once installed, your AI tool gains access to these capabilities:

• analyze_video — send any video file or URL through 8 analysis modes
• check_job_status — poll results for large files that process in the background
• check_credits — see your remaining credit balance
• list_recent_jobs — view past analyses
• get_account — check account details

The 8 analysis modes cover different use cases:

Processing takes under 60 seconds for most videos. Your video file is deleted immediately after processing — only the text output is kept.

Prerequisites

You need two things:

1. Python 3.10+ installed on your machine
2. A VidContext API key — sign up free at vidcontext.com/app, then go to Developer → API Keys and create one. You get 20 free credits on signup.

Setup for Claude Desktop

Open your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the VidContext server to the mcpServers section:

{
  "mcpServers": {
    "vidcontext": {
      "command": "python3",
      "args": ["-m", "vidcontext_mcp"],
      "env": {
        "VIDCONTEXT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop. You should see a hammer icon with the VidContext tools listed.

Now you can say things like:

• "Analyze this video" (drag a file into the chat)
• "What's happening in this product demo?"
• "Score this ad for effectiveness"
• "Give me an editor timeline with timestamps for this clip"

The MCP server uses a guided workflow — it walks the AI through each step (file path → mode selection → results), so you don't need to remember any syntax.

Setup for Claude Code

Claude Code supports global MCP configuration. Run this in your terminal:

claude mcp add vidcontext \
  -s user \
  -e VIDCONTEXT_API_KEY=your-api-key-here \
  -- python3 -m vidcontext_mcp

That's it. Every Claude Code session now has access to video analysis. Try it:

> analyze this video: /path/to/your/video.mp4

Claude Code will ask which analysis mode you want, run the analysis, and show you the full structured output.

Setup for Cursor

Open your Cursor MCP config. Go to Settings → MCP Servers and add:

{
  "mcpServers": {
    "vidcontext": {
      "command": "python3",
      "args": ["-m", "vidcontext_mcp"],
      "env": {
        "VIDCONTEXT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Cursor. The video analysis tools will be available in Cursor's AI chat.

Setup for any MCP-compatible tool

The pattern is the same for any tool that supports MCP:

• Command: python3 -m vidcontext_mcp
• Environment variable: VIDCONTEXT_API_KEY=your-key

If the tool uses a JSON config, the format above works universally. If it uses command-line registration, pass those two values however the tool expects them.

What the output looks like

Here's a real example. I asked Claude to analyze a 30-second product demo using the editor mode:

[00:00.0 - 00:03.2] WIDE SHOT — App dashboard loads with dark UI.
  Logo visible top-left, navigation sidebar on left.
  Smooth fade-in animation. No audio.

[00:03.2 - 00:08.5] SCREEN RECORDING — User clicks "Upload" button.
  Drag-and-drop zone appears with dashed border.
  File browser opens, user selects "demo-clip.mp4" (4.2MB).
  Subtle click sound effect.

[00:08.5 - 00:15.0] PROCESSING STATE — Upload progress bar fills.
  Spinner appears with text "Analyzing video..."
  Credit counter decrements from 5 to 4.
  Background: soft ambient music begins.

[00:15.0 - 00:24.8] RESULTS VIEW — Analysis output renders in markdown.
  Scroll reveals: scene descriptions, timestamps, scoring table.
  Highlighted sections with color-coded severity badges.
  Text on screen: "Complete analysis in 12 seconds"

[00:24.8 - 00:30.0] OUTRO — Product name "VidContext" with tagline.
  CTA text: "Give your AI agent eyes — vidcontext.com"
  Fade to black. Music fades.

Every timestamp, every visual element, every piece of on-screen text — extracted and structured. An editor can use this to navigate the timeline without watching the video. An AI agent can use it to answer questions about what the video contains.

The other modes produce similarly detailed but differently structured output. The ad mode scores messaging effectiveness. The analysis mode evaluates creator performance. The context mode gives a rich narrative description. Each mode is designed for a specific workflow.

Batch processing

The MCP server also supports folder-level batch processing. Point it at a folder of videos (up to 10), and it processes them sequentially, returning a summary table with job IDs for each.

This is useful for:

• Analyzing a competitor's entire YouTube channel
• Vetting a batch of UGC submissions
• Processing dailies from a video shoot
• Auditing a library of training videos

Just give the AI a folder path instead of a single file, and the guided workflow handles the rest.

Large file handling

Files over 95MB are uploaded to a temporary storage bucket, and processing happens in the background. The MCP server returns a job ID immediately, and you can check the status later with check_job_status.

This means even long-form content (up to 500MB, 15 minutes) works without timing out. The AI tool will automatically tell you how to check back for results.

Pricing

You get 5 free analyses without an account, and 20 credits when you sign up. After that:

• Credit packs start at $10 for 50 credits (1 credit = 1 minute of video, rounded up)
• Pro (BYOK) subscription: $29/month or $249/year for unlimited processing with your own Gemini key

Full pricing details at vidcontext.com/#pricing.

Troubleshooting

"Module not found" error: Make sure you installed with pip install vidcontext-mcp (not just vidcontext). If you have multiple Python versions, try python3.12 -m pip install vidcontext-mcp to target a specific one.

Tools not showing up: Restart the AI tool after changing the config. Claude Desktop needs a full quit and relaunch, not just closing the window.

"Invalid API key" error: Double-check that you copied the full key (starts with vc_) and that it's in the env section of your config, not the args section.

Upload timeout on large files: Files over 95MB process asynchronously. The tool will return a job ID — use check_job_status to get the results when they're ready.

What's next

The MCP server is open source: github.com/cold-reboot/vidcontext. If you build something interesting with it, we'd love to hear about it — join the Discord or email support@vidcontext.com.

VidContext is a video intelligence API that turns video into structured text. Available as a REST API and MCP server. Get started free →