ken-api-mcp

🎬 Ken Video API MCP Server

A comprehensive Model Context Protocol (MCP) server that provides LLMs with full access to the Ken Video API's professional video processing capabilities. Perfect for automation workflows, especially n8n integrations.

🚀 Quick Start

Installation

npm install -g ken-api-mcp

Claude Desktop Integration

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "ken-video-api": {
      "command": "ken-api-mcp"
    }
  }
}

n8n Integration

Use with the MCP node in n8n for powerful video automation workflows.

🎯 Perfect For n8n Workflows

AI Video Generation Pipeline

Stable Diffusion → RunwayML → Ken Video API MCP
    (image)      →  (video)  →  (voice + captions)

Workflow Steps:

1. Generate image with Stable Diffusion
2. Convert to video with RunwayML/Stable Video
3. Generate voice-over with ElevenLabs
4. Use ken_add_audio_from_urls to combine video + audio
5. Use ken_auto_caption_from_url to add captions
6. Use ken_process_and_download to get final video

🛠️ Available Tools

🔥 Priority Tools (Most Used in n8n)

ken_add_audio_from_urls

Add voice-over or background audio to videos using URLs.

{
  "video_url": "https://runwayml.com/output.mp4",
  "audio_url": "https://elevenlabs.com/voice.mp3", 
  "volume": 0.8
}

ken_auto_caption_from_url

Generate automatic captions with AI transcription.

{
  "video_url": "https://your-video.mp4",
  "language": "en",
  "font_size": 16,
  "position": "bottom"
}

ken_check_job_status

Monitor job progress and completion.

{
  "job_id": "12345-abcd-5678"
}

ken_process_and_download

Wait for job completion and download the result in one step.

{
  "job_id": "12345-abcd-5678",
  "max_wait_time": 600
}

⚙️ Management Tools

• ken_check_api_health - Verify API availability
• ken_api_info - Get comprehensive API information
• ken_wait_for_job - Poll until job completion
• ken_download_video - Download processed videos
• ken_cancel_job - Cancel running jobs

🎬 Advanced Processing

• ken_process_batch_operations - Execute multiple operations
• ken_create_video_with_audio_and_captions - High-level automation tool
• File upload tools (require file system access)

🔗 Webhook Management

• ken_create_webhook - Set up job notifications
• ken_list_webhooks - View webhook configurations
• ken_delete_webhook - Remove webhooks

📊 Configuration

Environment Variables

# Optional configuration
export KEN_API_BASE_URL="https://ken-video-api-production.up.railway.app"
export KEN_API_TIMEOUT="120000"  # 2 minutes
export KEN_API_RETRIES="3"
export KEN_API_LOGGING="true"    # Enable debug logs

Default Configuration

• Base URL: ken-video-api-production.up.railway.app
• Timeout: 2 minutes for requests
• Retries: 3 attempts with exponential backoff
• Job Polling: 5-second intervals with intelligent backoff
• Max Poll Time: 10 minutes for job completion

🎬 Example n8n Workflow

Complete Video Creation Automation

# n8n Workflow: AI Video with Voice-over and Captions
1. HTTP Request (Stable Diffusion)
   → Generate image from text prompt

2. HTTP Request (RunwayML)  
   → Convert image to video

3. HTTP Request (ElevenLabs)
   → Generate voice-over from script

4. MCP Tool: ken_add_audio_from_urls
   → Combine video + voice-over
   → Returns: job_id

5. MCP Tool: ken_wait_for_job  
   → Wait for audio overlay completion
   → Returns: completed job status

6. MCP Tool: ken_auto_caption_from_url
   → Add captions to video with audio
   → Returns: job_id  

7. MCP Tool: ken_process_and_download
   → Download final video with voice + captions
   → Returns: video binary data

8. Upload to Social Media
   → Post to Twitter, YouTube, etc.

🔧 API Coverage

Supported Ken Video API Endpoints:

• ✅ Health checking (2 endpoints)
• ✅ URL-based processing (2 endpoints) - Primary for n8n
• ✅ Job management (3 endpoints) - Essential for automation
• ✅ Webhook management (4 endpoints)
• ✅ Batch processing (1 endpoint)
• ⚠️ File upload endpoints (7 endpoints) - Limited by MCP file access

Total: 19 tools covering 18 API endpoints

🛡️ Error Handling

Intelligent Error Recovery

• Automatic retries with exponential backoff
• Rate limit handling with wait suggestions
• Connection error recovery with health checks
• Job timeout management with manual status checks

LLM-Friendly Error Messages

{
  "success": false,
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "API rate limit reached. Please wait 60 seconds before retry.",
  "suggestion": "Consider using batch operations for multiple videos",
  "retry_after": 60
}

📈 Performance

Optimized for Automation

• Smart job polling with adaptive intervals
• Concurrent operation support
• Memory-efficient file handling
• Graceful error fallbacks

Railway Production Ready

• 2GB file size limit (Railway optimized)
• Sub-5 second response times for job creation
• 99%+ uptime on Railway infrastructure
• Global CDN delivery for fast downloads

🔒 Security

Built-in Protection

• URL validation prevents SSRF attacks
• Input sanitization for all parameters
• Rate limit awareness prevents API abuse
• Error masking prevents information disclosure

📚 Development

Local Development

git clone https://github.com/ken/ken-api-mcp.git
cd ken-api-mcp
npm install
npm run dev

Building

npm run build
npm run typecheck
npm run lint

Publishing

npm run prepublishOnly
npm publish

🆘 Troubleshooting

Common Issues

"Connection Error"

• Check API health: Use ken_check_api_health
• Verify base URL configuration
• Confirm internet connectivity

"Job Not Found"

• Jobs are cleaned up after completion
• Use job status immediately after creation
• Check job ID format is correct

"Rate Limit Exceeded"

• Wait 60 seconds before retry
• Consider batch operations for multiple requests
• Monitor usage patterns

"File Not Found"

• Files are temporary and cleaned up quickly
• Download immediately after job completion
• Use ken_process_and_download for automatic download

Debug Mode

Enable detailed logging:

export KEN_API_LOGGING=true

🎉 Success Stories

Perfect for:

• 🎬 AI video generation pipelines
• 🗣️ Voice-over automation workflows
• 📝 Automatic captioning systems
• 🎞️ Video format conversion services
• 🔄 Batch video processing operations

Used in production for:

• Social media content automation
• Educational video creation
• Marketing video pipelines
• Accessibility compliance
• Multi-language video localization

📞 Support

• Issues: GitHub Issues
• API Documentation: Ken Video API Docs
• MCP Protocol: MCP Documentation

---

Make your video automation workflows incredibly powerful with Ken Video API MCP! 🚀