Troubleshooting
This guide covers common issues you might encounter while using the VFX MCP Server and provides step-by-step solutions to resolve them.
🚨 Installation Issues
Section titled “🚨 Installation Issues”FFmpeg Not Found
Section titled “FFmpeg Not Found”Symptoms:
- Error: “FFmpeg not found in PATH”
- Tool calls fail with “ffmpeg command not found”
Solutions:
-
Verify FFmpeg Installation:
Terminal window # Check if FFmpeg is installedffmpeg -versionffprobe -version# If not found, install FFmpeg# Ubuntu/Debian:sudo apt update && sudo apt install ffmpeg# macOS with Homebrew:brew install ffmpeg# Windows: Download from https://ffmpeg.org/download.html -
Set FFmpeg Path Manually:
Terminal window # Add to your environmentexport FFMPEG_PATH=/usr/bin/ffmpegexport FFPROBE_PATH=/usr/bin/ffprobe# Or in Windows:set FFMPEG_PATH=C:\path\to\ffmpeg.exeset FFPROBE_PATH=C:\path\to\ffprobe.exe -
Using Nix Development Environment:
Terminal window # Recommended approach - includes FFmpeg automaticallynix develop# FFmpeg paths are set automatically
Python Dependencies Issues
Section titled “Python Dependencies Issues”Symptoms:
- ImportError for required packages
- “Module not found” errors
Solutions:
-
Reinstall Dependencies:
Terminal window # Using uv (recommended)uv sync --force-reinstall# Using pippip install --force-reinstall -r requirements.txt -
Check Python Version:
Terminal window # Verify Python 3.9+python --version# Use specific version if neededpython3.9 -m pip install -r requirements.txt -
Virtual Environment Issues:
Terminal window # Create fresh virtual environmentpython -m venv vfx_envsource vfx_env/bin/activate # Linux/macOS# orvfx_env\Scripts\activate # Windowspip install -r requirements.txt
🔌 MCP Connection Issues
Section titled “🔌 MCP Connection Issues”Server Won’t Start
Section titled “Server Won’t Start”Symptoms:
- Server exits immediately
- “Connection refused” errors
- No response to MCP client connections
Solutions:
-
Check Server Logs:
Terminal window # Run server with debug loggingexport VFX_LOG_LEVEL=DEBUGuv run python main.py# Look for specific error messages -
Verify Working Directory:
Terminal window # Ensure you're in the correct directorycd /path/to/vfx-mcpls main.py # Should exist# Check permissionsls -la main.py -
Port Conflicts (for SSE transport):
Terminal window # Check if port is in usenetstat -an | grep 8000# Use different portexport MCP_PORT=8001
Claude Desktop Connection Failed
Section titled “Claude Desktop Connection Failed”Symptoms:
- Claude Desktop shows “Server failed to start”
- Tools not available in Claude Desktop
Solutions:
-
Verify Configuration File:
~/.config/claude/claude_desktop_config.json {"mcpServers": {"vfx-server": {"command": "uv","args": ["run", "python", "main.py"],"cwd": "/absolute/path/to/vfx-mcp"}}} -
Check Absolute Paths:
Terminal window # Use absolute paths, not relativepwd # Get current directory# Use this full path in configuration -
Test Server Independently:
Terminal window # Test server startupcd /path/to/vfx-mcpuv run python main.py# Should start without errors -
Restart Claude Desktop:
- Quit Claude Desktop completely
- Wait 10 seconds
- Restart Claude Desktop
- Try again
🎬 Video Processing Issues
Section titled “🎬 Video Processing Issues”Tool Execution Failures
Section titled “Tool Execution Failures”Symptoms:
- “FFmpeg error” messages
- Tool calls timeout
- Corrupted output files
Solutions:
-
Verify Input Files:
# Check if input file exists and is accessibleimport osprint(os.path.exists("input_video.mp4"))print(os.access("input_video.mp4", os.R_OK))# Check file formatinfo = await session.call_tool("get_video_info", {"video_path": "input_video.mp4"})print(info) -
Check Disk Space:
Terminal window # Verify sufficient disk spacedf -h .# Clean up temporary filesrm -f temp_*.mp4 -
File Permissions:
Terminal window # Fix file permissionschmod 644 input_video.mp4chmod 755 output_directory/
Codec and Format Issues
Section titled “Codec and Format Issues”Symptoms:
- “Unsupported codec” errors
- Format conversion failures
- Audio/video sync issues
Solutions:
-
Check Supported Formats:
# Get server capabilitiescapabilities = await session.read_resource("tools://capabilities")print("Supported input formats:", capabilities['format_support']['input_formats'])print("Supported output formats:", capabilities['format_support']['output_formats']) -
Convert Problematic Files:
Terminal window # Convert to standard format firstffmpeg -i problematic_video.avi -c:v libx264 -c:a aac standard_video.mp4 -
Use Format Conversion Tool:
# Convert using VFX MCP Serverawait session.call_tool("convert_format", {"input_path": "input.avi","output_path": "output.mp4","video_codec": "libx264","audio_codec": "aac"})
Performance Issues
Section titled “Performance Issues”Symptoms:
- Slow processing
- High CPU/memory usage
- Operations timing out
Solutions:
-
Optimize Quality Settings:
# Use lower quality for faster processingawait session.call_tool("resize_video", {"input_path": "large_video.mp4","output_path": "resized.mp4","width": 1280,"height": 720,"quality": "medium" # Instead of "ultra"}) -
Process in Smaller Chunks:
# Split large videos into smaller segmentsduration = 600 # 10 minutesfor i in range(0, int(total_duration), duration):await session.call_tool("trim_video", {"input_path": "large_video.mp4","output_path": f"chunk_{i}.mp4","start_time": i,"duration": duration}) -
Monitor System Resources:
# Check server capabilitiescapabilities = await session.read_resource("tools://capabilities")resources = capabilities['system_resources']if resources['cpu_usage'] > 80:print("High CPU usage - consider reducing concurrent operations")if resources['memory_usage'] > 90:print("High memory usage - restart server if needed")
📁 File and Path Issues
Section titled “📁 File and Path Issues”File Not Found Errors
Section titled “File Not Found Errors”Symptoms:
- “No such file or directory”
- Path resolution failures
Solutions:
-
Use Absolute Paths:
# Instead of relative pathsimport osabsolute_path = os.path.abspath("relative_video.mp4")await session.call_tool("trim_video", {"input_path": absolute_path,"output_path": os.path.abspath("output.mp4"),"start_time": 0,"duration": 30}) -
Check Working Directory:
Terminal window # Verify current working directorypwdls *.mp4 # List video files# Or set working directoryexport VFX_WORK_DIR=/path/to/videos -
List Available Files:
# Use resource endpoint to see available filesvideo_list = await session.read_resource("videos://list")print("Available videos:")for video in video_list['videos']:print(f"- {video['name']}")
Output Directory Issues
Section titled “Output Directory Issues”Symptoms:
- “Permission denied” when writing output
- Output files not created
Solutions:
-
Create Output Directory:
Terminal window # Ensure output directory existsmkdir -p output_videoschmod 755 output_videos -
Check Write Permissions:
Terminal window # Test write permissionstouch test_output.txtrm test_output.txt # Should work without errors -
Use Temporary Directory:
import tempfileimport os# Use system temporary directorytemp_dir = tempfile.gettempdir()output_path = os.path.join(temp_dir, "output.mp4")
🔧 Configuration Issues
Section titled “🔧 Configuration Issues”Environment Variables
Section titled “Environment Variables”Symptoms:
- Server uses wrong settings
- Paths not resolved correctly
Solutions:
-
Check Environment Variables:
Terminal window # List VFX-related environment variablesenv | grep VFXenv | grep MCPenv | grep FFMPEG -
Set Required Variables:
Terminal window # Set essential environment variablesexport VFX_WORK_DIR=/path/to/videosexport MCP_TRANSPORT=stdioexport VFX_LOG_LEVEL=INFO -
Create Environment File:
Terminal window # Create .env file in project directorycat > .env << EOFVFX_WORK_DIR=/path/to/videosMCP_TRANSPORT=stdioFFMPEG_PATH=/usr/bin/ffmpegFFPROBE_PATH=/usr/bin/ffprobeEOF
Server Configuration
Section titled “Server Configuration”Symptoms:
- Wrong transport mode
- Server binding to wrong address/port
Solutions:
- Verify Transport Configuration:
# Check current transport modeimport ostransport = os.getenv('MCP_TRANSPORT', 'stdio')print(f"Transport mode: {transport}")# For Claude Desktop, use stdioos.environ['MCP_TRANSPORT'] = 'stdio'# For web applications, use sseos.environ['MCP_TRANSPORT'] = 'sse'os.environ['MCP_HOST'] = 'localhost'os.environ['MCP_PORT'] = '8000'
🧪 Testing and Debugging
Section titled “🧪 Testing and Debugging”Enable Debug Mode
Section titled “Enable Debug Mode”# Enable comprehensive loggingexport VFX_LOG_LEVEL=DEBUGuv run python main.py 2>&1 | tee debug.log
Test Individual Tools
Section titled “Test Individual Tools”# Test basic connectivityasync def test_basic_functionality(): try: # Test video info tool info = await session.call_tool("get_video_info", { "video_path": "test_video.mp4" }) print("✅ get_video_info works")
# Test simple trim result = await session.call_tool("trim_video", { "input_path": "test_video.mp4", "output_path": "test_output.mp4", "start_time": 0, "duration": 5 }) print("✅ trim_video works")
except Exception as e: print(f"❌ Test failed: {e}") import traceback traceback.print_exc()
System Information
Section titled “System Information”# Gather system information for debuggingasync def collect_debug_info(): import platform import sys
print("System Information:") print(f"Platform: {platform.platform()}") print(f"Python: {sys.version}")
# Server capabilities try: capabilities = await session.read_resource("tools://capabilities") print(f"Server version: {capabilities['server_info']['version']}") print(f"FFmpeg version: {capabilities['ffmpeg_info']['version']}") print(f"Available encoders: {capabilities['ffmpeg_info']['encoders']}") except Exception as e: print(f"Could not get server capabilities: {e}")
🆘 Getting Help
Section titled “🆘 Getting Help”Before Seeking Help
Section titled “Before Seeking Help”- Check this troubleshooting guide
- Review the FAQ
- Enable debug logging and capture the output
- Test with a simple video file to isolate the issue
Reporting Issues
Section titled “Reporting Issues”When reporting issues, please include:
-
System Information:
- Operating system and version
- Python version
- FFmpeg version
- VFX MCP Server version
-
Error Details:
- Full error message
- Debug logs
- Steps to reproduce
-
Configuration:
- Environment variables
- MCP client configuration
- Working directory structure
Community Support
Section titled “Community Support”- GitHub Issues: Report bugs and request features
- FAQ: Check common questions
- Performance Guide: See optimization tips
🔄 Recovery Procedures
Section titled “🔄 Recovery Procedures”Clean Installation
Section titled “Clean Installation”If all else fails, perform a clean installation:
# 1. Remove existing installationrm -rf vfx-mcp/
# 2. Fresh clonegit clone https://github.com/conneroisu/vfx-mcp.gitcd vfx-mcp
# 3. Clean Python environmentpython -m venv fresh_envsource fresh_env/bin/activate
# 4. Install dependenciesuv sync
# 5. Test installationuv run python main.py
Reset Configuration
Section titled “Reset Configuration”# Remove configuration filesrm -f ~/.config/claude/claude_desktop_config.jsonrm -f .env
# Recreate with minimal configurationmkdir -p ~/.config/claudecat > ~/.config/claude/claude_desktop_config.json << EOF{ "mcpServers": { "vfx-server": { "command": "uv", "args": ["run", "python", "main.py"], "cwd": "$(pwd)" } }}EOF
Still having issues? Check our FAQ or file an issue with detailed information about your problem.