popcorn
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@popcorn Analyze /Users/me/video.mp4 for transcript and key scenes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Quick Start
# Install FFmpeg (required)
brew install ffmpeg # macOS
sudo apt install ffmpeg # Ubuntu/Debian
# Install Popcorn
git clone https://github.com/anthropics/popcorn.git
cd popcorn && npm install && npm run build
# Optional: Install a transcription backend
pip install mlx-whisper # Apple Silicon (fastest)
pip install openai-whisper # Any platformAdd to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"popcorn": {
"command": "node",
"args": ["/path/to/popcorn/dist/index.js"]
}
}
}Key Features:
Scene Detection — Captures frames at visual transitions, not fixed intervals
Local Transcription — 4 backend options (mlx-whisper, faster-whisper, whisper-cpp, whisper)
Inline Images — Returns key frames directly in MCP responses
Smart Presets — Auto-configures for screencasts, presentations, movies, interviews
Zero Config — Just pass a video path and it works
Privacy First — Everything runs locally, no data leaves your machine
Related MCP server: mcp-video
Documentation
Getting Started
Quick Start — Installation & setup
Tutorial — Step-by-step usage guide
MCP Tools — Available tools reference
Guides
Transcription Backends — Choose the best backend for your system
Video Types & Objectives — Presets for different content
Configuration — Advanced parameters
Reference
Troubleshooting — Common issues & solutions
Agent Skill — Instructions for AI agents
API Reference — Tool schemas & responses
How It Works
Core Components:
FFprobe — Extracts video metadata (duration, resolution, codecs)
FFmpeg Scene Detection — Finds visual transitions using
select='gt(scene,N)'filterParallel Frame Extraction — Captures JPEGs at scene change timestamps
Multi-Backend Transcription — Whisper variants convert audio to timestamped text
Analysis Bundle — Results saved to
.popcorn/directoryMCP Response — Returns metadata + inline base64 images
Video File ──▶ FFprobe ──▶ FFmpeg ──▶ Whisper ──▶ Analysis Bundle
│ │ │ │
▼ ▼ ▼ ▼
metadata frames transcript MCP ResponseMCP Tools
Tool | Description |
| Main analysis — extracts frames, transcribes audio, returns results |
| Probe video metadata and get recommended settings |
| List available video types and objectives |
| Detect your system and show transcription options |
| Read transcript slices with time filtering |
Basic Usage
{
"tool": "popcorn_analyze",
"arguments": {
"path": "/path/to/video.mp4"
}
}With Presets
{
"tool": "popcorn_analyze",
"arguments": {
"path": "/path/to/video.mp4",
"videoType": "screencast",
"objective": "detailed"
}
}Video Types
Type | Best For | Scene Detection |
| Tutorials, coding sessions, UI demos | Low threshold |
| Slides, lectures, keynotes | Slide transitions |
| Films, TV shows | Balanced |
| Podcasts, talking heads | Transcription priority |
| Security footage, dashcam | High threshold |
| Live events, fast action | High frame rate |
Objectives
Objective | Use When |
| Quick overview needed |
| Don't miss anything |
| Searching for specific content |
| Audio/speech is most important |
| Only care about visuals |
| Fast preview needed |
Transcription Backends
Popcorn auto-detects your system and recommends the best backend.
Backend Comparison
Backend | Speed | Best For | Install |
mlx-whisper | Fastest | Apple Silicon (M1/M2/M3/M4) |
|
faster-whisper | Fast | NVIDIA GPUs |
|
whisper-cpp | Moderate | Cross-platform |
|
whisper | Slow | Most compatible |
|
Processing Times (60-min video)
Backend | Time |
mlx-whisper | 3-8 min |
faster-whisper | 5-10 min |
whisper-cpp | 10-20 min |
whisper | 30-60 min |
Force a Backend
{
"tool": "popcorn_analyze",
"arguments": {
"path": "/path/to/video.mp4",
"backend": "mlx-whisper"
}
}Configuration
All Parameters
Parameter | Type | Description |
| string | Required. Absolute path to video file |
| string | Video type preset |
| string | Analysis objective preset |
| boolean | Enable/disable transcription |
| string | Transcription backend |
| string | Whisper model ( |
| string | Language code (e.g., |
| string |
|
| number | Scene sensitivity (0-1) |
| number | Maximum frames to extract |
| number | Frames to return as base64 |
Output Structure
.popcorn/<video>_<timestamp>/
├── analysis.json # Full metadata
├── transcript.txt # Plain text
├── transcript.json # Timestamped segments
├── transcript.chunks.json # LLM-friendly chunks
└── assets/
├── audio.wav
└── frames/
├── scene_000001.jpg
└── ...Troubleshooting
FFmpeg not found
brew install ffmpeg # macOS
sudo apt install ffmpeg # Ubuntu/DebianNo transcription backend
pip install mlx-whisper # Apple Silicon
pip install openai-whisper # Any platformToo few frames detected
{ "sceneThreshold": 0.15, "minSceneInterval": 2 }Too many frames detected
{ "sceneThreshold": 0.5, "minSceneInterval": 10 }See Troubleshooting Guide for more solutions.
Development
npm install # Install dependencies
npm run build # Build
npm run dev # Development mode
npm start # Run serverProject Structure
popcorn/
├── src/
│ ├── index.ts # MCP server
│ ├── analyze.ts # Analysis pipeline
│ ├── ffmpeg.ts # Video processing
│ ├── transcribe.ts # Multi-backend transcription
│ ├── presets.ts # Video type presets
│ └── commands.ts # Shell execution
├── docs/ # Documentation
└── skills/ # Agent skillsContributing
Fork the repository
Create a feature branch (
git checkout -b feature/amazing)Commit changes (
git commit -m 'Add amazing feature')Push to branch (
git push origin feature/amazing)Open a Pull Request
License
MIT License — see LICENSE for details.
Acknowledgments
OpenAI Whisper — Speech recognition
whisper.cpp — C++ port
MLX Whisper — Apple Silicon
faster-whisper — CTranslate2
FFmpeg — Video processing
Model Context Protocol — MCP spec
Available Tools
5 toolspopcorn_analyzeA
Analyze a video file. Extracts keyframes and transcripts. RECOMMENDED: First use popcorn_suggest to get optimal settings, or specify videoType and objective to use smart presets.
Inputs: path (required), model, outDir, backend, +12 more.
popcorn_backendsA
List available transcription backends on this system. Shows which backends are installed and ready to use. Use this to help users choose the best transcription option.
Inputs: no named parameters.
popcorn_presetsA
List all available video type presets and objectives. Use this to understand what options are available for popcorn_analyze.
Inputs: no named parameters.
popcorn_readA
Read a file from an analysis bundle with optional line slicing or transcript time filtering.
Inputs: path (required), endSec, endLine, maxChars, +2 more.
popcorn_suggestA
Probe a video file and get suggested analysis settings. Returns video metadata, suggested video type, and recommended presets. Use this FIRST to understand the video and choose appropriate settings before running popcorn_analyze.
Inputs: path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clear, distinct purpose: suggest probes and recommends settings, presets lists options, analyze performs the analysis, read accesses results, and backends shows system capabilities. No two tools appear to do the same thing.
All tools share a consistent popcorn_ prefix, but the suffix style mixes verbs (suggest, analyze, read) with nouns (presets, backends). This is a minor deviation from a uniform verb_noun pattern, but the names are still predictable and readable.
With 5 tools, the set is well-scoped for video analysis. Each tool covers a distinct step in the workflow (probe, list options, analyze, read output, check backends), earning its place without redundancy.
The tool surface provides a complete workflow: suggest gives metadata and recommended settings, analyze runs the analysis, and read retrieves results. Presets and backends offer configuration information. No critical operations are missing for the stated purpose.
Maintenance
Related MCP Connectors
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
MCP server for Wan AI video generation
An MCP server that gives any LLM or agent clean YouTube transcripts on demand: a single video, a whole channel, or a playlist, plus AI cleanup of auto-generated captions. API-key auth, credit-based, same backend as the public v1 API. Get a free API key with 25 free credits at youtubetranscriptdownload.com/account.
MCP server for Google Veo AI video generation
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA local MCP server for extracting YouTube video transcripts, metadata, and performing visual analysis using Gemini Vision or local Whisper models. It enables users to process video content through various tools for subtitle retrieval and frame analysis.23 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables LLMs to analyze video content by extracting frames as base64 images and retrieving video metadata using ffmpeg.5 npmMIT
- AlicenseNot gradedqualityAmaintenanceMCP server that enables AI agents to watch and analyze videos from 1800+ sources, with persistent indexing, OCR, transcription, and a self-verification loop for debugging.MIT
- AlicenseAqualityDmaintenanceMCP server that analyzes videos locally with frame-by-frame understanding and optional browser sidecars, producing structured context bundles for coding agents to fix bugs, add features, or build new functionality.142Apache 2.0