# 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

```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): `"context"` (default) or `"analysis"`

**Modes:**
- **Context mode** — 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 mode** — Expert analysis scored across 7 proprietary frameworks: Hook, Retention, Scripting, CTA, Editing, Performance, and Platform Optimization. Built from a corpus of 2,000+ expert videos.

**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](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)
