-
securityF
license-
qualityEnables AI language models to interact with YouTube content through a standardized interface, providing tools for retrieving video information, transcripts, channel analytics, and trend analysis.
Last updated -
363
47
Used for video processing, including frame extraction and scene detection in video files
Used for version control of the codebase and managing contributions
Platform for project hosting, issue reporting, and community discussions
Provides local LLM inference capabilities using models like Llava for vision analysis and Mistral for chat interactions
Testing framework used for running unit and integration tests
Core programming language required to run the server (3.10+)
MCP Video Parser
A powerful video analysis system that uses the Model Context Protocol (MCP) to process, analyze, and query video content using AI vision models.
๐ฌ Features
AI-Powered Video Analysis: Automatically extracts and analyzes frames using vision LLMs (Llava)
Natural Language Queries: Search videos using conversational queries
Time-Based Search: Query videos by relative time ("last week") or specific dates
Location-Based Organization: Organize videos by location (shed, garage, etc.)
Audio Transcription: Extract and search through video transcripts
Chat Integration: Natural conversations with Mistral/Llama while maintaining video context
Scene Detection: Intelligent frame extraction based on visual changes
MCP Protocol: Standards-based integration with Claude and other MCP clients
๐ Quick Start
Prerequisites
Python 3.10+
Ollama installed and running
ffmpeg (for video processing)
Installation
Clone the repository:
git clone https://github.com/michaelbaker-dev/mcpVideoParser.git
cd mcpVideoParser
Install dependencies:
pip install -r requirements.txt
Pull required Ollama models:
ollama pull llava:latest # For vision analysis
ollama pull mistral:latest # For chat interactions
Start the MCP server:
python mcp_video_server.py --http --host localhost --port 8000
Basic Usage
Process a video:
python process_new_video.py /path/to/video.mp4 --location garage
Start the chat client:
python standalone_client/mcp_http_client.py --chat-llm mistral:latest
Example queries:
"Show me the latest videos"
"What happened at the garage yesterday?"
"Find videos with cars"
"Give me a summary of all videos from last week"
๐๏ธ Architecture
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ Video Files โโโโโโถโ Video Processor โโโโโโถโ Frame Analysis โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ โ
โผ โผ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ MCP Server โโโโโโโ Storage Manager โโโโโโโ Ollama LLM โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโ
โ HTTP Client โ
โโโโโโโโโโโโโโโโโโโ
๐ ๏ธ Configuration
Edit config/default_config.json to customize:
Frame extraction rate: How many frames to analyze
Scene detection sensitivity: When to capture scene changes
Storage settings: Where to store videos and data
LLM models: Which models to use for vision and chat
See Configuration Guide for details.
๐ง MCP Tools
The server exposes these MCP tools:
process_video- Process and analyze a video filequery_location_time- Query videos by location and timesearch_videos- Search video content and transcriptsget_video_summary- Get AI-generated summary of a videoask_video- Ask questions about specific videosanalyze_moment- Analyze specific timestamp in a videoget_video_stats- Get system statisticsget_video_guide- Get usage instructions
๐ ๏ธ Utility Scripts
Video Cleanup
Clean all videos from the system and reset to a fresh state:
# Dry run to see what would be deleted
python clean_videos.py --dry-run
# Clean processed files and database (keeps originals)
python clean_videos.py
# Clean everything including original video files
python clean_videos.py --clean-originals
# Skip confirmation and backup
python clean_videos.py --yes --no-backup
This script will:
Remove all video entries from the database
Delete all processed frames and transcripts
Delete all videos from the location-based structure
Optionally delete original video files
Create a backup of the database before cleaning (unless
--no-backup)
Video Processing
Process individual videos:
# Process a video with automatic location detection
python process_new_video.py /path/to/video.mp4
# Process with specific location
python process_new_video.py /path/to/video.mp4 --location garage
๐ Documentation
API Reference - Detailed MCP tool documentation
Configuration Guide - Customization options
Video Analysis Info - How video processing works
Development Guide - Contributing and testing
Deployment Guide - Production setup
๐ฆ Development
Running Tests
# All tests
python -m pytest tests/ -v
# Unit tests only
python -m pytest tests/unit/ -v
# Integration tests (requires Ollama)
python -m pytest tests/integration/ -v
Project Structure
mcp-video-server/
โโโ src/
โ โโโ llm/ # LLM client implementations
โ โโโ processors/ # Video processing logic
โ โโโ storage/ # Database and file management
โ โโโ tools/ # MCP tool definitions
โ โโโ utils/ # Utilities and helpers
โโโ standalone_client/ # HTTP client implementation
โโโ config/ # Configuration files
โโโ tests/ # Test suite
โโโ video_data/ # Video storage (git-ignored)
๐ค Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
๐ Roadmap
โ Basic video processing and analysis
โ MCP server implementation
โ Natural language queries
โ Chat integration with context
๐ง Enhanced time parsing (see INTELLIGENT_QUERY_PLAN.md)
๐ง Multi-camera support
๐ง Real-time processing
๐ง Web interface
๐ Troubleshooting
Common Issues
Ollama not running:
ollama serve # Start Ollama
Missing models:
ollama pull llava:latest
ollama pull mistral:latest
Port already in use:
# Change port in command
python mcp_video_server.py --http --port 8001
๐ License
MIT License - see LICENSE for details.
๐ Acknowledgments
Built on FastMCP framework
Uses Ollama for local LLM inference
Inspired by the Model Context Protocol specification
๐ฌ Support
Version: 0.1.1
Author: Michael Baker
Status: Beta - Breaking changes possible
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A video analysis system that uses AI vision models to process, analyze, and query video content through natural language, enabling users to search videos by time, location, and content.
Related MCP Servers
- -securityAlicense-qualityAn agent-based tool that provides web search and advanced research capabilities including document analysis, image description, and YouTube transcript retrieval.Last updated -12Apache 2.0
- AsecurityFlicenseAqualityEnables natural language search and interaction with video content through three tools: ingesting videos to a Ragie index, retrieving relevant video segments based on queries, and creating video chunks from specific timestamps.Last updated -31
- AsecurityFlicenseAqualityEnables comprehensive video file analysis including extracting metadata, stream information, bitrate calculations, and generating technical reports. Supports all FFmpeg-compatible video formats with output in JSON, text, or Markdown formats.Last updated -491