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
- Install dependencies:```bash
pip install -r requirements.txt
2. **Configure credentials**:```bash
cp .env.example .env
# Edit .env with your API credentials (see setup sections below)
- Start the server:```bash
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```http
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:```json
{
"success": true,
"video_id": "dQw4w9WgXcQ",
"watch_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
### Upload to Instagram Reels```http
POST /upload/instagram
Content-Type: multipart/form-data
file: <video_file>
caption: "Check out my new reel! #viral #reels"
Response:```json
{
"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```python
await post_to_youtube(
title="My Video Title",
description="Video description",
tags=["tag1", "tag2", "tag3"],
video_path="/path/to/video.mp4"
)
post_to_instagram```python
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:```env
# 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```bash
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```bash
python test_server.py
Error Handling
The server provides detailed error responses:```json
{
"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:```bash
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:```env
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:```json
{
"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```bash
DEBUG=True python main.py
### Testing the API```bash
# 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
-
YouTube Authentication Errors
- Verify OAuth credentials are correct
- Check if access token has expired
- Ensure YouTube Data API v3 is enabled -
Instagram Upload Failures
- Verify Instagram Business/Creator account is linked
- Check access token permissions
- Ensure video meets Instagram requirements -
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:bash
DEBUG=True python main.py
License
MIT License - see LICENSE file for details.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
Support
For issues and questions:
- Check the troubleshooting section
- Review API documentation
- Open an issue on GitHub