rough-cut-mcp

🎬 Rough Cut MCP

A comprehensive Model Context Protocol (MCP) server that integrates Remotion video creation with AI-powered services for complete video production workflows.

✨ Features

🎬 Complete Video Production Pipeline

• Remotion: Programmatic video creation and rendering
• ElevenLabs: AI voice generation for narration
• Freesound: Sound effects search and download
• Flux AI: AI image generation for visual assets

🛠 Modular Architecture

• Layered Tool System: Reduces context bloat, improves performance
• Port Persistence: Projects remember their studio ports across sessions
• Comprehensive Error Handling: Graceful failure recovery
• Asset Lifecycle Management: Automatic cleanup and organization
• TypeScript: Full type safety throughout

📊 Smart Asset Management

• Automatic directory organization
• Disk usage monitoring and cleanup
• File type validation
• Project metadata tracking

🚀 Quick Start

Installation

# Install globally
npm install -g rough-cut-mcp

# Or install locally in your project
npm install rough-cut-mcp

Automatic Claude Desktop Setup

# Automatically configure Claude Desktop
npx rough-cut-mcp install-to-claude

This will:

• Build the project
• Find your Claude Desktop configuration
• Add the MCP server entry
• Provide setup instructions

Manual Configuration

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "rough-cut-mcp": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\path\\to\\rough-cut-mcp\\build\\index.js"
      ],
      "env": {
        "NODE_ENV": "production",
        "REMOTION_ASSETS_DIR": "D:\\path\\to\\your\\assets"
      }
    }
  }
}

📋 Prerequisites

• Node.js 18+
• Windows OS (primary platform, required for full Claude Desktop integration)
• macOS (experimental support - see macOS Installation section below)
• API Keys for services you want to use:
  • ElevenLabs for voice generation
  • Freesound for sound effects
  • Black Forest Labs for Flux image generation

🍎 macOS Installation (Experimental)

⚠️ Experimental Support: macOS compatibility is provided for sharing purposes. Windows remains the primary platform with full feature support.

Prerequisites for macOS

• Node.js 18+ (install via Homebrew recommended)
• Claude Desktop for Mac (available from Anthropic)

Installation on macOS

# Install Node.js via Homebrew (recommended)
brew install node

# Install the MCP server
npm install -g rough-cut-mcp

# Build the project
cd /usr/local/lib/node_modules/rough-cut-mcp
npm run build

macOS Claude Desktop Configuration

Add to your Claude Desktop claude_desktop_config.json (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "rough-cut-mcp": {
      "command": "/usr/local/bin/node",
      "args": [
        "/usr/local/lib/node_modules/rough-cut-mcp/build/index.js"
      ],
      "env": {
        "NODE_ENV": "production",
        "REMOTION_ASSETS_DIR": "/Users/yourusername/Documents/rough-cut-assets"
      }
    }
  }
}

Alternative Node.js Paths on macOS

Depending on your Node.js installation:

# Homebrew installation
"command": "/usr/local/bin/node"

# Node Version Manager (nvm)
"command": "/Users/yourusername/.nvm/versions/node/v20.x.x/bin/node"

# Official Node.js installer
"command": "/usr/local/bin/node"

macOS Limitations & Known Issues

• Remotion Studio: May have launch issues - Windows has better integration
• File Paths: Some tools may expect Windows-style paths
• Performance: Not optimized for macOS filesystem
• Testing: Limited testing compared to Windows platform

Getting Your Node.js Path on macOS

# Find your Node.js installation
which node

# Verify Node.js version
node --version

macOS Asset Directory Setup

# Create asset directory
mkdir -p ~/Documents/rough-cut-assets

# Set permissions
chmod 755 ~/Documents/rough-cut-assets

🔧 Configuration

Environment Variables

Create a .env file in your assets directory:

# Required for voice generation
ELEVENLABS_API_KEY=your_elevenlabs_key_here

# Required for sound effects
FREESOUND_API_KEY=your_freesound_key_here

# Required for image generation  
FLUX_API_KEY=your_flux_key_here

Tool Organization

The MCP server uses a layered tool architecture for better performance:

• Discovery Tools (always active): Tool management and exploration
• Core Operations (default): Basic project and studio operations
• On-Demand Categories: Video creation, voice generation, image tools, etc.

🎯 Usage

Basic Workflow

• Discover Available Tools:

  Use "discover-capabilities" to see all tool categories
  

• Activate Tool Categories:

  Use "activate-toolset" to load specific tool sets:
  - video-creation
  - studio-management
  - voice-generation (requires API key)
  - sound-effects (requires API key)
  - image-generation (requires API key)
  

• Create and Edit Videos:

  - "create-complete-video" - Generate full video projects
  - "launch-project-studio" - Open Remotion Studio for editing
  - "edit-video-element" - Programmatically modify video elements
  

Example Commands

# List all video projects
"list-video-projects"

# Create a new animated video
"create-complete-video" with parameters:
{
  "name": "my-awesome-video",
  "template": "text-animation",
  "duration": 300
}

# Launch Remotion Studio for a specific project
"launch-project-studio" with parameters:
{
  "projectName": "my-awesome-video"
}

🛠 Available Tools

Core Operations (Always Active)

• list-video-projects - List all animation projects
• get-project-status - Get project information and health
• launch-project-studio - Launch Remotion Studio with port persistence

Video Creation Tools

• create-complete-video - Create new video with React components
• create-text-video - Simple text-based animations
• edit-video-element - Modify specific elements in compositions
• analyze-video-structure - Understand project composition

Studio Management Tools

• launch-remotion-studio - Start Remotion Studio dashboard
• stop-remotion-studio - Stop running studio instances
• get-studio-status - Check studio health and status
• launch-studio-with-project - Launch studio for specific project

Voice Generation Tools (ElevenLabs)

• generate-voice - Create AI voiceovers
• list-voices - Browse available voices
• clone-voice - Clone custom voices

Sound Effects Tools (Freesound)

• search-sound-effects - Find sound effects
• download-sound-effects - Download audio files
• get-sound-info - Audio file details

Image Generation Tools (Flux)

• generate-image - Create AI images
• generate-styled-image - Images with specific styles
• upscale-image - Enhance image resolution

Asset Management Tools

• get-asset-statistics - Disk usage and file counts
• cleanup-old-assets - Remove temporary files
• organize-assets - Sort files by type

🔍 Advanced Features

Port Persistence

Projects automatically remember their Remotion Studio port assignments:

• First launch assigns a port (7400-7600 range)
• Subsequent launches reuse the same port
• Metadata stored in .studio-metadata.json

Smart Tool Loading

The layered architecture improves performance:

• Initial load: 9 tools instead of 40+
• Dynamic loading based on needs
• Reduced context and faster responses

Asset Lifecycle Management

• Automatic cleanup of temporary files
• Disk usage monitoring
• Project organization and categorization

📁 Project Structure

rough-cut-mcp/
├── build/                 # Compiled TypeScript
├── src/                   # Source code
│   ├── tools/            # MCP tool implementations
│   ├── services/         # Core services
│   ├── utils/           # Utilities
│   └── types/           # TypeScript definitions
├── assets/              # Asset storage
│   ├── projects/        # Video projects
│   ├── voices/          # Generated audio
│   ├── images/          # Generated images
│   └── sounds/          # Sound effects
└── tests/               # Test suites

🧪 Testing

# Run all tests
npm test

# Test specific components
npm run test-layered      # Test tool architecture
npm run test-routing      # Test tool routing fixes
npm run test-studio       # Test studio integration

🚀 Publishing & Distribution

For NPM Package

# Build and test before publishing
npm run prepublishOnly

# Publish to NPM
npm publish

For Local Development

# Build project
npm run build

# Install to Claude Desktop
npm run install-to-claude

📝 API Reference

Tool Categories

Category	Description	Requires API Key
discovery	Tool management and exploration	No
core-operations	Basic project operations	No
video-creation	Video and animation tools	No
studio-management	Remotion Studio control	No
voice-generation	ElevenLabs TTS	Yes
sound-effects	Freesound integration	Yes
image-generation	Flux AI images	Yes
maintenance	Asset management	No

MCP Protocol Compliance

This server fully implements the Model Context Protocol:

• ✅ Tool discovery and listing
• ✅ Dynamic tool activation
• ✅ JSON-RPC over stdio
• ✅ Error handling and recovery
• ✅ Resource management

🐛 Troubleshooting

Common Issues

Q: Tools not appearing after activation
A: Check that the MCP server is running and Claude Desktop configuration is correct.

Q: Remotion Studio won't launch
A: Ensure you're on Windows and have Node.js 18+ installed. Check port availability (7400-7600).

Q: API-dependent tools missing
A: Verify API keys are set in environment variables or config.

Q: Build fails on non-Windows platforms
A: Windows is the primary platform. macOS support is experimental - see macOS Installation section.

Debug Mode

Set debug logging in your environment:

NODE_ENV=development
LOG_LEVEL=debug

🤝 Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests if applicable
• Run npm run prepublishOnly to validate
• Submit a pull request

📄 License

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

🚨 Important Licensing Notice

This software uses Remotion libraries which have their own licensing requirements:

• Remotion is FREE for individuals and teams up to 3 people
• Companies with 4+ members require a Remotion Company License
• Some @remotion/* packages are MIT licensed (e.g., @remotion/media-utils, @remotion/shapes)
• Core Remotion packages require compliance with Remotion licensing terms

Before using this software in a commercial environment, please:

• Review the Remotion License
• Check if you need a Company License
• See Terms & Conditions

Users are responsible for ensuring compliance with all third-party licensing requirements.

🙏 Acknowledgments

• Remotion for programmatic video creation
• Model Context Protocol for the integration standard
• ElevenLabs for AI voice generation
• Freesound for sound effects database
• Black Forest Labs for Flux image generation

📞 Support

• 🐛 Report Issues
• 💬 Discussions
• 📧 Support: [e-mail]

Made with ❤️ for the Claude Desktop and Remotion communities

Changelog

[3.0.1] - 2025-08-29

Fixed

• CRITICAL: Fixed JSX syntax error in video creation templates causing "undefined component" errors
• CRITICAL: Removed hardcoded test projects from package that were causing VM installation issues
• Fixed missing React imports and inconsistent TypeScript types in generated templates
• Fixed unclosed JSX tags in AbsoluteFill components

Removed

• Eliminated bundled test projects from git tracking and npm package
• Removed unused RemotionRoot exports from templates
• Cleaned up assets/projects directory from repository

Improved

• Enhanced template generation with proper TypeScript annotations
• Better error handling for component compilation issues
• Cleaner package distribution without broken example projects