VMRam95/mcp-video

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:

• get_video_info - Get video metadata
• 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

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 for detailed architecture, future roadmap, and implementation plans.

License

MIT