vidcontext-mcp 0.2.0

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 7 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")

7 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.
• 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 (useful if processing timed out on a long video).

Parameters:

• job_id (required): The job ID from a previous analyze_video call

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
• Max duration: 15 minutes
• Processing time: 30-180 seconds depending on length

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