MCP Video

An MCP (Model Context Protocol) server that enables LLMs to analyze video content by extracting frames and transcribing audio.

Features

• Frame Extraction: Extract key frames from videos as base64-encoded images
• Video Metadata: Get duration, resolution, codec, file size, and more
• Configurable: Adjust frame interval, quality, resolution, and time range
• Multiple Formats: MP4, WebM, MOV, AVI, MKV, GIF, and more

Current Status

Phase 1 (MVP) - Complete:

• [x] get_video_info - Get video metadata
• [x] extract_frames - Extract frames at intervals

Phase 2 (Coming Soon):

• [ ] transcribe_audio - Audio transcription with Whisper
• [ ] analyze_video - Combined frames + transcription

Prerequisites

• Node.js >= 18
• ffmpeg installed on system

Install ffmpeg

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows (with chocolatey)
choco install ffmpeg

Installation

# Clone or navigate to the repository
cd mcp-video

# Install dependencies
npm install

# Build
npm run build

Configuration for Claude Code

Add to your MCP settings file:

Location: ~/.claude/mcp_servers/mcp-video.json (create if doesn't exist)

Or add to your Claude Code settings:

{
  "mcpServers": {
    "mcp-video": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/Documentos/repositories/mcp-video/dist/index.js"]
    }
  }
}

Replace YOUR_USERNAME with your actual username.

Available Tools

get_video_info

Get metadata about a video file.

Input:

{
  path: string  // Path to video file
}

Output:

{
  "filename": "video.mp4",
  "duration": "02:30",
  "duration_seconds": 150,
  "resolution": "1920x1080",
  "fps": 30,
  "codec": "h264",
  "audio_codec": "aac",
  "file_size": "45.2 MB",
  "has_audio": true
}

extract_frames

Extract frames from video at specified intervals.

Input:

{
  path: string;          // Path to video file (required)
  interval?: number;     // Seconds between frames (default: 2)
  max_frames?: number;   // Max frames to extract (default: 30)
  quality?: number;      // JPEG quality 1-100 (default: 75)
  width?: number;        // Frame width in pixels (default: 800)
  start_time?: number;   // Start from this second
  end_time?: number;     // End at this second
}

Output:

• Video metadata as text
• Array of base64-encoded JPEG images

Usage Examples

Once configured, you can use it in Claude Code:

"What's the duration and resolution of /path/to/video.mp4?"
→ Uses get_video_info

"Show me frames from /path/to/video.mp4 every 5 seconds"
→ Uses extract_frames with interval=5

"Extract the first 10 frames from /path/to/video.mp4"
→ Uses extract_frames with max_frames=10

"Get frames from 10 to 30 seconds of the video"
→ Uses extract_frames with start_time=10, end_time=30

Supported Video Formats

Format	Extension	Support
MP4	.mp4	Full
WebM	.webm	Full
MOV	.mov	Full
AVI	.avi	Full
MKV	.mkv	Full
GIF	.gif	Frames only
M4V	.m4v	Full
FLV	.flv	Full
WMV	.wmv	Full
MPEG	.mpeg, .mpg	Full

Development

# Run in development mode (with hot reload)
npm run dev

# Build for production
npm run build

# Type check
npm run typecheck

# Run tests
npm test

Project Structure

mcp-video/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server setup
│   ├── tools/
│   │   ├── get-video-info.ts # Metadata tool
│   │   └── extract-frames.ts # Frame extraction tool
│   ├── processors/
│   │   └── ffmpeg-processor.ts # FFmpeg wrapper
│   ├── utils/
│   │   ├── validators.ts     # Input validation
│   │   └── file-handler.ts   # File operations
│   └── types/
│       └── index.ts          # TypeScript types
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
├── PLANNING.md               # Detailed architecture
└── README.md

Documentation

See PLANNING.md for detailed architecture, future roadmap, and implementation plans.

License

MIT