sidart10/runway-mcp-server

Runway MCP Server

A Model Context Protocol (MCP) server for Runway ML, providing comprehensive AI video generation and editing capabilities through Gen-4, Veo 3, and Aleph models.

MCP Registry Name: io.github.sidart10/runway-mcp-server

Table of Contents

• Features
• Installation
• Configuration
• Available Tools
• Usage Examples
• Documentation
• Project Structure
• Rate Limits
• Troubleshooting
• Testing
• Contributing
• License
• Resources

Features

Video Generation

• Text-to-Video - Generate videos from text descriptions using Veo 3 models
• Image-to-Video - Animate static images with Gen-4 and Gen-3 models
• Keyframe Control - Precise control with first/last frame specification

Video Editing

• Aleph Video Editing - Advanced video-to-video transformations:
  • Add, remove, or replace objects in existing videos
  • Change camera angles and generate novel views
  • Transform lighting, style, and environments
  • Generate shot continuations

Image Generation

• Gen-4 Image Models - High-fidelity image generation with reference support
• Reference Images - Consistent characters and styles using tagged references

Advanced Tools

• Video Extension - Extend videos by 5-10 seconds
• 4K Upscaling - Enhance videos to 4K resolution
• Style Transfer - Apply artistic styles to existing videos

Installation

Option 1: Install from PyPI (Recommended)

# Install with uvx (automatically manages dependencies)
uvx runway-mcp-server

# Or install globally with pip
pip install runway-mcp-server

Option 2: Install from Source

# Clone the repository
git clone https://github.com/sidart10/runway-mcp-server.git
cd runway-mcp-server

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Mac/Linux
# venv\Scripts\activate    # Windows

# Install in development mode
pip install -e .

Requirements

• Python 3.10 or higher
• Runway API key from dev.runwayml.com

Configuration

Step 1: Configure API Key

Set your Runway API key as an environment variable or in a .env file:

# .env file
RUNWAY_API_KEY=your_api_key_here

Step 2: Add to MCP Client Configuration

For Cursor:

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "runway": {
      "command": "uvx",
      "args": ["runway-mcp-server"],
      "env": {
        "RUNWAY_API_KEY": "your_api_key_here"
      }
    }
  }
}

For Claude Desktop:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "runway": {
      "command": "uvx",
      "args": ["runway-mcp-server"],
      "env": {
        "RUNWAY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Step 3: Restart Client

Restart Cursor or Claude Desktop to load the server.

Available Tools

The server exposes the following MCP tools:

Usage Examples

Generate Video from Text

Generate a 6-second video of a golden retriever and orange cat sitting together on a cozy couch with warm cinematic lighting

Edit Video with Aleph

Edit this video to remove all people from the scene: https://example.com/video.mp4

Animate an Image

Animate this image with a time-lapse of clouds moving across the sky: https://example.com/sunset.jpg

Generate Image with Reference

Generate a Gen-4 image of @Hero standing on a mountaintop at sunset, 1920x1080 resolution

Style Transfer

Transform this video into a vibrant watercolor painting style: https://example.com/video.mp4

Documentation

Getting Started

• - Installation and setup walkthrough
• - Comprehensive feature documentation
• - In-depth video editing guide

Technical Documentation

• - System design and implementation patterns
• - Code quality and design review
• - Automated test suite results

Development

• - Instructions for publishing updates
• - Package structure details
• - Running and writing tests

Project Structure

runway-mcp-server/
├── src/                           # Package source code
│   └── runway_mcp_server/
│       ├── __init__.py            # Package initialization
│       └── server.py              # Main server implementation
├── docs/                          # Documentation
│   ├── QUICKSTART.md              # Quick start guide
│   ├── ARCHITECTURE.md            # System architecture
│   ├── ARCHITECTURE_REVIEW.md     # Code review
│   ├── FEATURES.md                # Feature documentation
│   ├── ALEPH_GUIDE.md             # Aleph editing guide
│   ├── TEST_RESULTS.md            # Test reports
│   ├── PUBLISHING_GUIDE.md        # Publishing instructions
│   └── PACKAGE_TRANSFORMATION_SUMMARY.md  # Packaging details
├── tests/                         # Test suite
│   ├── test_server.py             # Comprehensive tests
│   └── README.md                  # Testing guide
├── config/                        # Configuration templates
│   └── mcp_config_example.json    # Example MCP configuration
├── pyproject.toml                 # Package configuration
├── server.json                    # MCP Registry metadata
├── requirements.txt               # Python dependencies
├── .env.example                   # Environment template
├── README.md                      # This file
└── .env                           # API key (create this)

Rate Limits

API usage is rate-limited based on your Runway subscription plan:

• Gen-4 Turbo: Approximately 5 credits per second of video
• Aleph Editing: Approximately 15 credits per second of video
• Gen-3 Alpha: Varies by model and settings

Monitor your usage and check credit balance at dev.runwayml.com.

Troubleshooting

API Key Not Loading

Verify your .env file exists and contains the API key:

# Check if .env file exists
ls -la .env

# Verify key loads correctly
python -c "from dotenv import load_dotenv; import os; load_dotenv(); print('OK' if os.getenv('RUNWAY_API_KEY') else 'MISSING')"

Server Won't Start

1. Verify Python version: python3 --version (must be 3.10+)
2. Ensure virtual environment is activated
3. Check dependencies are installed: pip list | grep mcp
4. Review server logs for specific error messages

Task Timeouts

Video generation is compute-intensive and may take several minutes:

• Text-to-video: 2-5 minutes
• Image-to-video: 3-7 minutes
• Aleph editing: 5-10 minutes
• 4K upscaling: 3-5 minutes

Use get_task_status(task_id) to monitor progress instead of waiting synchronously.

Import Errors

If you encounter import errors after installation:

# Reinstall the package
pip uninstall runway-mcp-server
pip install runway-mcp-server

# Or for development
pip install -e .

Testing

Run the comprehensive test suite:

# Activate virtual environment
source venv/bin/activate

# Run tests
python tests/test_server.py

Expected output: All tests should pass with detailed results.

See for detailed testing documentation.

Contributing

Contributions are welcome! This project follows the Model Context Protocol specification.

Development Setup

1. Fork the repository
2. Clone your fork: git clone https://github.com/your-username/runway-mcp-server.git
3. Create a branch: git checkout -b feature/your-feature
4. Install in development mode: pip install -e .
5. Make your changes
6. Run tests: python tests/test_server.py
7. Commit and push: git commit -am "Add feature" && git push origin feature/your-feature
8. Open a pull request

Code Style

• Follow PEP 8 style guidelines
• Include docstrings for all functions
• Add type hints where appropriate
• Write tests for new features

License

MIT License - see LICENSE file for details.

This MCP server is provided as-is for use with the Runway API. Runway API usage is subject to Runway's terms of service.

Resources

• Runway Developer Portal: dev.runwayml.com
• Runway API Documentation: docs.dev.runwayml.com
• MCP Specification: modelcontextprotocol.io
• MCP Registry: registry.modelcontextprotocol.io
• PyPI Package: pypi.org/project/runway-mcp-server
• Issue Tracker: github.com/sidart10/runway-mcp-server/issues

Support

For issues or questions:

1. Check the
2. Search existing issues
3. Review Runway's help center
4. Open a new issue if needed

Built for the Runway AI community

For updates and announcements, watch this repository or follow development on GitHub.