vidcontext-mcp 0.5.1

MCP server for VidContext — Give your AI agent eyes

VidContext MCP Server

Give your AI agent eyes. Analyze any video directly from Claude Desktop, Cursor, or Claude Code.

VidContext processes video files and returns detailed text descriptions or expert analysis scored across 8 specialized modes with proprietary frameworks — letting any AI model understand video content.

Quick Start

1. Install

pip install vidcontext-mcp

Or with uv (recommended):

uv pip install vidcontext-mcp

2. Get Your API Key

1. Sign up at vidcontext.com
2. Purchase a credit pack (required for API access)
3. Go to Developer Settings
4. Create an API key — save it, it's shown only once

3. Configure Your AI Tool

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "vidcontext": {
      "command": "vidcontext-mcp",
      "env": {
        "VIDCONTEXT_API_KEY": "vc_your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop. You'll see a hammer icon in the chat input showing VidContext tools.

Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "vidcontext": {
      "command": "vidcontext-mcp",
      "env": {
        "VIDCONTEXT_API_KEY": "vc_your_api_key_here"
      }
    }
  }
}

Claude Code

claude mcp add vidcontext -- vidcontext-mcp

Then set your API key as an environment variable:

export VIDCONTEXT_API_KEY="vc_your_api_key_here"

Available Tools

analyze_video

The main tool. Upload a video file or URL, get back a complete text analysis.

Parameters:

• file_path (required): Local file path or URL to a video
• output_format (optional): Analysis mode (default: "context")

8 Analysis Modes:

• context — Detailed scene-by-scene description with timestamps, transcript, visual elements, audio, and on-screen text. Perfect for giving any AI model "eyes" to understand video content.
• editor — Frame-by-frame breakdown for AI video editors. Sub-second timeline mapping, cut points, zoom cues, caption timing, B-roll windows, and pacing data. Designed for multi-pass editing workflows.
• analysis — Creator/social media analysis scored across 7 frameworks: Hook, Retention, Scripting, CTA, Editing, Performance, and Platform Optimization.
• ad — Ad effectiveness scoring across 6 frameworks: Message Clarity, Brand Presence, Persuasion, Audience Targeting, Platform Optimization, and Legal Compliance. Score: 1-100.
• ecommerce — Product video analysis across 6 frameworks: Product Visibility, Feature Demonstration, Purchase Psychology, Lifestyle Integration, Platform Commerce, and Thumbnail. Platform-specific weights (Amazon, TikTok Shop, Shopify, etc.). Score: 1-100.
• training — Pedagogical effectiveness across 6 frameworks: Learning Objective, Cognitive Load, Knowledge Scaffolding, Visual Reinforcement, Engagement, and Assessment Readiness. Score: 1-10.
• ugc — Creator vetting for brand partnerships across 6 frameworks: Production Quality, Authenticity, Brand Integration, Audience Alignment, Brand Safety, and Whitelisting Potential. Returns Creator Quality, Brand Fit, and Overall Vetting scores.
• competitor — Competitive intelligence across 6 frameworks: Messaging Strategy, Target Audience, Production Investment, Content Strategy, Differentiation, and Distribution. Returns Threat Score (1-100) and Quality Score (1-100).

Example prompts:

• "Analyze the video at ~/Downloads/demo.mp4"
• "Give me an expert analysis of this video: /path/to/video.mov"
• "Describe what happens in https://example.com/video.mp4"

check_job_status

Check on a previous analysis job or retrieve results.

Parameters:

• job_id (required): The job ID from analyze_video or list_recent_jobs

list_recent_jobs

List video analysis jobs submitted during this session. Shows job IDs, modes, and filenames. Useful for checking on jobs or retrieving results from earlier in the conversation.

check_credits

See your current credit balance, tier, and usage limits.

get_account

View your account details, subscription status, and credit information.

Pricing

• 1 credit = 1 minute of video (rounded up)
• Credit packs: 10/$5, 50/$20, 250/$80
• Subscriptions: Starter $15/mo (40 credits), Pro $35/mo (100 credits), Business $69/mo (250 credits)

Supported Formats

MP4, MOV, AVI, MKV, WebM, M4V, FLV, WMV

Limits:

• Max file size: 500MB (files >95MB automatically upload via presigned URLs)
• Max duration: 15 minutes
• Processing time: 30-180 seconds depending on length

How It Works

1. You pass a file path or URL to analyze_video
2. The tool uploads the video, handles large files automatically, and tracks progress
3. Processing takes 30-180 seconds — the tool sends progress heartbeats to keep the connection alive
4. The full analysis is returned as text

The tool handles retries on rate limits automatically. If processing takes longer than expected, use list_recent_jobs and check_job_status to retrieve results.

Important: Always analyze the original video file. Don't compress or modify it first — that changes the content and produces inaccurate results.

Troubleshooting

"VIDCONTEXT_API_KEY not set" — Make sure your API key is in the env section of your MCP config.

"Insufficient credits" — Buy more at vidcontext.com.

"Invalid API key" — Double-check your key at Developer Settings. Keys start with vc_.

Tool not showing up — Restart Claude Desktop/Cursor after editing the config file.

Links

• Website: vidcontext.com
• Developer Settings: vidcontext.com/app/developer