# 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

```bash
pip install vidcontext-mcp
```

Or with [uv](https://docs.astral.sh/uv/) (recommended):

```bash
uv pip install vidcontext-mcp
```

### 2. Get Your API Key

1. Sign up at [vidcontext.com](https://www.vidcontext.com)
2. Purchase a credit pack (required for API access)
3. Go to [Developer Settings](https://www.vidcontext.com/app/developer)
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):

```json
{
  "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):

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

#### Claude Code

```bash
claude mcp add vidcontext -- vidcontext-mcp
```

Then set your API key as an environment variable:

```bash
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](https://www.vidcontext.com).

**"Invalid API key"** — Double-check your key at [Developer Settings](https://www.vidcontext.com/app/developer). Keys start with `vc_`.

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

## Links

- Website: [vidcontext.com](https://www.vidcontext.com)
- Developer Settings: [vidcontext.com/app/developer](https://www.vidcontext.com/app/developer)
