instagram-video-analyzer-mcp

Morfeu333/instagram-video-analyzer-mcp

3.3

If you are the rightful owner of instagram-video-analyzer-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Instagram Video Analyzer MCP Server is a comprehensive tool for analyzing Instagram videos using AI, providing transcription, visual analysis, and content insights.

Tools
6
Resources
0
Prompts
0

🎬 Instagram Video Analyzer MCP Server

A comprehensive Model Context Protocol (MCP) server for analyzing Instagram videos using AI. This server enables Claude and other LLMs to analyze Instagram content with advanced AI capabilities including transcription, visual analysis, and content insights.

🎯 What This Does

Transform Instagram videos into actionable insights using AI:

  • 📝 Transcription: Convert speech to text with timestamps
  • 👁️ Visual Analysis: Detailed scene-by-scene descriptions
  • 🧠 Content Insights: Extract key themes, emotions, and engagement factors
  • 📊 Performance Metrics: Track analysis jobs and system health
  • 🔄 Real-time Processing: Monitor progress with live updates

Perfect for: Content creators, marketers, researchers, and AI enthusiasts who need to analyze Instagram video content at scale.

🌟 Features

🛠️ 6 Powerful Tools

  • analyze_instagram_video - Complete video analysis with AI
  • get_job_status - Monitor analysis progress
  • list_recent_analyses - View recent analysis history
  • cancel_job - Cancel running analyses
  • get_system_stats - System performance metrics
  • get_video_info - Basic video information

📚 3 Dynamic Resources

  • analysis://{job_id} - Access specific analysis results
  • jobs://recent - Recent jobs overview
  • stats://system - Real-time system statistics

🎯 Analysis Types

  • Comprehensive - Full analysis with transcription, visual description, and insights
  • Transcription - Audio-to-text conversion only
  • Visual Description - Detailed visual content analysis
  • Summary - Concise content overview

🚀 Quick Start

Prerequisites

  • Python 3.11+
  • Google AI API Key (for Gemini)
  • Claude Code or compatible MCP client
  • FFmpeg (for video processing)

⚡ 5-Minute Setup

  1. Clone and setup:
git clone https://github.com/Morfeu333/instagram-video-analyzer-mcp.git
cd instagram-video-analyzer-mcp
  1. Start the backend:
cd backend
pip install -r requirements.txt
# Add your GOOGLE_API_KEY to .env file
python -m app.main
  1. Install and run MCP server:
cd mcp-server
uv sync
uv run instagram-video-analyzer-mcp
  1. Configure Claude Code (see for details)

Claude Code Configuration

Add to your Claude Code configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "instagram-video-analyzer": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-server", "run", "instagram-video-analyzer-mcp"],
      "env": {
        "API_BASE_URL": "http://localhost:8000",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

📖 Usage Examples

🎬 Basic Video Analysis

Analyze this Instagram video: https://www.instagram.com/reel/DMiEEmlMI7J/

Result: Complete transcription + visual analysis + content insights

📝 Transcription Only

Get only the transcription of this video: https://www.instagram.com/reel/DMiEEmlMI7J/

Result: Timestamped speech-to-text conversion

👁️ Visual Analysis

Describe the visual content of this video: https://www.instagram.com/reel/DMiEEmlMI7J/

Result: Scene-by-scene visual descriptions

📊 Batch Analysis

Analyze these 5 Instagram videos and compare their content themes:
- https://www.instagram.com/reel/video1/
- https://www.instagram.com/reel/video2/
- https://www.instagram.com/reel/video3/

🔍 System Monitoring

Show me the system statistics and recent analyses

Result: Performance metrics, job history, disk usage

🔧 API Reference

Tools

analyze_instagram_video

Analyzes an Instagram video using AI.

Parameters:

  • url (string, required): Instagram video URL
  • analysis_type (string, optional): Type of analysis
    • comprehensive (default): Complete analysis
    • transcription: Audio transcription only
    • visual_description: Visual content analysis
    • summary: Concise overview

Returns:

{
  "success": true,
  "job_id": "uuid-string",
  "status": "completed",
  "analysis": {
    "analysis_type": "comprehensive",
    "model_used": "gemini-2.5-flash",
    "raw_response": "Detailed analysis...",
    "file_size": 19058688
  }
}
get_job_status

Retrieves the status of an analysis job.

Parameters:

  • job_id (string, required): Job identifier

Returns:

{
  "job_id": "uuid-string",
  "status": "completed",
  "progress": 100,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:32:30Z",
  "analysis_result": { ... }
}
list_recent_analyses

Lists recent video analyses.

Parameters:

  • limit (int, optional): Maximum results (default: 10)
  • page (int, optional): Page number (default: 1)
cancel_job

Cancels a running analysis job.

Parameters:

  • job_id (string, required): Job to cancel
get_system_stats

Retrieves system performance statistics.

Returns:

{
  "total_jobs": 150,
  "completed_jobs": 142,
  "failed_jobs": 3,
  "pending_jobs": 5,
  "success_rate": 94.67,
  "average_processing_time": 125.5
}
get_video_info

Gets basic information about an Instagram video.

Parameters:

  • url (string, required): Instagram video URL

Resources

analysis://{job_id}

Access detailed results of a specific analysis.

jobs://recent

Overview of recent analysis jobs.

stats://system

Real-time system performance metrics.

🎯 Advanced Features

Scene-by-Scene Analysis

The MCP server can provide synchronized analysis where each spoken phrase is matched with its corresponding visual scene:

Frase 1 (0:00-0:03): "Check out this amazing tip!"
Scene 1: Close-up of person's face, excited expression, blurred background...

Frase 2 (0:03-0:07): "You'll only need..."
Scene 2: Hands holding objects, organized desk, natural lighting...

Batch Processing

Analyze multiple videos and compare insights across content.

Real-time Monitoring

Track analysis progress and system performance in real-time.

🔍 Troubleshooting

Common Issues

MCP Server won't start:

  • Verify Python 3.11+ is installed
  • Check that the API is running: curl http://localhost:8000/health
  • Ensure all dependencies are installed: uv sync

Analysis fails:

  • Verify the Instagram URL is valid and public
  • Check API connectivity
  • Review logs for detailed error messages

Claude Code integration issues:

  • Verify configuration file path and syntax
  • Restart Claude Code after configuration changes
  • Check MCP server logs for connection errors

Logging

The server provides structured logging for debugging:

2024-01-15 10:30:00 INFO 🚀 Starting Instagram Video Analyzer MCP Server...
2024-01-15 10:30:01 INFO ✅ API connection established
2024-01-15 10:30:15 INFO 🎬 Starting video analysis: https://instagram.com/reel/...

🧪 Testing

Run the test suite:

cd mcp-server
uv run pytest tests/ -v

📁 Project Structure

instagram-video-analyzer-mcp/
├── 📂 backend/                        # FastAPI backend server
│   ├── app/
│   │   ├── main.py                    # FastAPI application
│   │   ├── database.py                # Database configuration
│   │   ├── models/                    # SQLAlchemy models
│   │   └── services/                  # AI analysis services
│   ├── requirements.txt
│   └── .env                          # Environment variables
├── 📂 mcp-server/                     # MCP bridge server
│   ├── instagram_video_analyzer_mcp.py
│   ├── pyproject.toml
│   └── tests/
├── 📂 data/                          # Storage directories
│   ├── videos/                       # Downloaded Instagram videos
│   ├── results/                      # Analysis results
│   └── temp/                         # Temporary processing files
├── 📂 docs/                          # Documentation
├── 📂 frontend/                      # Optional React frontend
├── 📂 vibekanban-templates/          # Automation workflows
├── 📄 README.md                      # This file
├── 📄 INSTALLATION_GUIDE.md          # Setup instructions
├── 📄 TECHNICAL_DOCUMENTATION.md     # Technical details
└── 📄 LICENSE                        # MIT License

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature-name
  3. Make your changes and add tests
  4. Commit your changes: git commit -am 'Add feature'
  5. Push to the branch: git push origin feature-name
  6. Submit a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

📚 Documentation

  • 📖 - Complete setup instructions
  • 🔧 - Architecture and API details
  • 🎯 - Common use cases
  • 🐛 - Common issues and solutions

🆘 Support

🎉 Acknowledgments

  • Built with FastMCP
  • Powered by Google Gemini AI
  • Instagram content processing via Instaloader

Made with ❤️ for the AI community