YouTube Shorts & Instagram Reels MCP Server

A Model Context Protocol (MCP) compatible FastAPI server that enables automated posting of videos to YouTube Shorts and Instagram Reels.

Features

• 🎬 YouTube Shorts Upload: Automatic detection and upload of short-form videos to YouTube
• 📱 Instagram Reels Upload: Direct upload to Instagram Reels with caption support
• 🔐 OAuth 2.0 Authentication: Secure authentication for both platforms
• 🛡️ File Validation: Comprehensive file type and size validation
• 🔄 Token Refresh: Automatic OAuth token refresh for YouTube
• 🎯 MCP Compatible: Full MCP tool integration for seamless automation
• ⚡ Async Operations: High-performance async file handling
• 📏 Video Processing: Automatic video duration detection using ffprobe

Quick Start

1. Install dependencies:

pip install -r requirements.txt

2. Configure credentials:

cp .env.example .env
# Edit .env with your API credentials (see setup sections below)

3. Start the server:

python main.py

4. Test the API:

• Visit http://localhost:8000/docs for interactive API documentation
• Use the /upload/youtube and /upload/instagram endpoints
• Access MCP tools at http://localhost:8000/mcp

API Endpoints

Upload to YouTube Shorts

POST /upload/youtube
Content-Type: multipart/form-data

file: <video_file>
title: "My Amazing Short"
description: "Check out this cool video!"
tags: "shorts,viral,amazing"

Response:

{
  "success": true,
  "video_id": "dQw4w9WgXcQ",
  "watch_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Upload to Instagram Reels

POST /upload/instagram
Content-Type: multipart/form-data

file: <video_file>
caption: "Check out my new reel! #viral #reels"

Response:

{
  "success": true,
  "reel_id": "17841234567890123",
  "permalink": "https://www.instagram.com/reel/ABC123def456/"
}

MCP Tool Usage

The server exposes two MCP tools for programmatic access:

post_to_youtube

await post_to_youtube(
    title="My Video Title",
    description="Video description",
    tags=["tag1", "tag2", "tag3"],
    video_path="/path/to/video.mp4"
)

post_to_instagram

await post_to_instagram(
    caption="My reel caption #hashtag",
    video_path="/path/to/video.mp4"
)

Prerequisites & Setup

YouTube API Setup

1. Google Cloud Console:

   • Go to Google Cloud Console
   • Create a new project or select existing one
   • Enable YouTube Data API v3 in the API Library
   • Create OAuth 2.0 credentials (Desktop application)

2. Get OAuth Tokens:

   • Use Google OAuth 2.0 Playground
   • Configure with your Client ID and Secret
   • Select https://www.googleapis.com/auth/youtube.upload scope
   • Complete OAuth flow and get access_token + refresh_token

Instagram API Setup

1. Facebook Developer Account:

   • Go to Facebook Developers
   • Create a new app (Business type)
   • Add Instagram Graph API product

2. Instagram Business Account:

   • Connect your Instagram Business/Creator account to a Facebook Page
   • Generate access token with proper permissions
   • Get your Instagram User ID

3. File Hosting (Required):

   • Instagram requires publicly accessible video URLs
   • Configure AWS S3, Cloudinary, or custom hosting in .env
   • Videos are temporarily uploaded to hosting service before Instagram API call

Configuration

Environment Variables

Copy .env.example to .env and configure:

# YouTube API Credentials
YOUTUBE_CLIENT_ID=your_client_id.apps.googleusercontent.com
YOUTUBE_CLIENT_SECRET=GOCSPX-your_client_secret
YOUTUBE_ACCESS_TOKEN=ya29.your_access_token
YOUTUBE_REFRESH_TOKEN=1//your_refresh_token

# Instagram API Credentials
INSTAGRAM_ACCESS_TOKEN=IGAAyour_instagram_token
INSTAGRAM_APP_ID=your_app_id
INSTAGRAM_APP_SECRET=your_app_secret
INSTAGRAM_USER_ID=your_user_id

# Server Configuration
HOST=0.0.0.0
PORT=8000
DEBUG=False

# File Upload Configuration
MAX_FILE_SIZE_MB=100
ALLOWED_VIDEO_EXTENSIONS=mp4,mov,avi,mkv,webm

File Requirements

Supported Formats

• Video: MP4, MOV, AVI, MKV, WebM
• Max Size: 100MB (configurable)
• Duration: Recommended under 60 seconds for optimal Shorts detection

YouTube Shorts Criteria

• Videos under 60 seconds are automatically tagged as Shorts
• Vertical or square aspect ratios work best
• Resolution: 1080x1920 (9:16) recommended

Instagram Reels Criteria

• Duration: 3-90 seconds
• Aspect ratio: 9:16 (vertical) recommended
• Resolution: 1080x1920 recommended

Testing

Test the Server

# Test health endpoint
curl http://localhost:8000/health

# Test YouTube upload
curl -X POST "http://localhost:8000/upload/youtube" \
  -F "file=@test_video.mp4" \
  -F "title=Test Video" \
  -F "description=Test Description" \
  -F "tags=test,api"

# Test Instagram upload
curl -X POST "http://localhost:8000/upload/instagram" \
  -F "file=@test_video.mp4" \
  -F "caption=Test reel #test"

Run Test Suite

python test_server.py

Error Handling

The server provides detailed error responses:

{
  "success": false,
  "error": "File too large. Maximum size is 100MB"
}

Common error scenarios:

• Invalid file format
• File too large
• Authentication failures
• API rate limits
• Network timeouts

Troubleshooting

Common Issues

1. YouTube Authentication Errors

   • Verify OAuth credentials are correct
   • Check if access token has expired (auto-refreshed)
   • Ensure YouTube Data API v3 is enabled

2. Instagram Upload Failures

   • Verify Instagram Business/Creator account is linked
   • Check access token permissions
   • Ensure video meets Instagram requirements
   • Configure file hosting (AWS S3, Cloudinary, etc.)

3. File Upload Issues

   • Check file size limits
   • Verify file format is supported
   • Ensure sufficient disk space for temporary files

Logs and Debugging

Enable debug mode for detailed logging:

DEBUG=True python main.py

Security Considerations

• Store credentials in environment variables, never in code
• Use HTTPS in production
• Implement rate limiting
• Validate all file uploads
• Monitor API usage quotas

License

MIT License - see LICENSE file for details.

File Requirements

Supported Formats

• Video: MP4, MOV, AVI, MKV, WebM
• Max Size: 100MB (configurable)
• Duration: Recommended under 60 seconds for optimal Shorts detection

YouTube Shorts Criteria

• Videos under 60 seconds are automatically tagged as Shorts
• Vertical or square aspect ratios work best
• Resolution: 1080x1920 (9:16) recommended

Instagram Reels Criteria

• Duration: 15-90 seconds
• Aspect ratio: 9:16 (vertical) recommended
• Resolution: 1080x1920 recommended

Configuration

Environment variables can be customized:

# Server Configuration
HOST=0.0.0.0
PORT=8000
DEBUG=False

# File Upload Configuration
MAX_FILE_SIZE_MB=100
ALLOWED_VIDEO_EXTENSIONS=mp4,mov,avi,mkv,webm

# API Rate Limiting
RATE_LIMIT_REQUESTS_PER_MINUTE=60

Error Handling

The server provides detailed error responses:

{
  "success": false,
  "error": "File too large. Maximum size is 100MB"
}

Common error scenarios:

• Invalid file format
• File too large
• Authentication failures
• API rate limits
• Network timeouts

Security Considerations

• Store credentials in environment variables, never in code
• Use HTTPS in production
• Implement rate limiting
• Validate all file uploads
• Monitor API usage quotas

Development

Running in Development Mode

DEBUG=True python main.py

Testing the API

# Test health endpoint
curl http://localhost:8000/health

# Test YouTube upload
curl -X POST "http://localhost:8000/upload/youtube" \
  -F "file=@test_video.mp4" \
  -F "title=Test Video" \
  -F "description=Test Description" \
  -F "tags=test,api"

Troubleshooting

Common Issues

1. YouTube Authentication Errors

   • Verify OAuth credentials are correct
   • Check if access token has expired
   • Ensure YouTube Data API v3 is enabled

2. Instagram Upload Failures

   • Verify Instagram Business/Creator account is linked
   • Check access token permissions
   • Ensure video meets Instagram requirements

3. File Upload Issues

   • Check file size limits
   • Verify file format is supported
   • Ensure sufficient disk space for temporary files

Logs and Debugging

Enable debug mode for detailed logging:

DEBUG=True python main.py

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Support

For issues and questions:

• Check the troubleshooting section
• Review API documentation
• Open an issue on GitHub