Metadata-Version: 2.4
Name: vidcontext-mcp
Version: 0.2.0
Summary: MCP server for VidContext — Give your AI agent eyes
Project-URL: Homepage, https://www.vidcontext.com
Project-URL: Documentation, https://www.vidcontext.com/app/developer
Author-email: VidContext <support@vidcontext.com>
License-Expression: MIT
Keywords: ai,analysis,claude,cursor,mcp,vidcontext,video
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.0.0
Description-Content-Type: text/markdown

# 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): 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](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)
