@imbsq/runway-mcp

Enhanced MCP (Model Context Protocol) server for Runway ML API with extended features.

Fork of: runway-api-mcp-server by Runway AI

What's Changed (vs Original)

✨ New Features

1. runway_textToVideo - New tool for text-to-video generation (no image required)

   • Supports models: veo3.1, veo3.1_fast, veo3, gen4.5, gen3a_turbo
   • Audio generation toggle
   • Async support with waitForCompletion=false

2. Async Mode - Added waitForCompletion parameter to video generation tools

   • waitForCompletion=true (default): Waits for task to complete, returns result
   • waitForCompletion=false: Returns task ID immediately for manual polling

3. Model gemini_2.5_flash - Added Google Gemini model support for image generation

🔧 Improvements

4. Updated runway_generateVideo

   • Added waitForCompletion option
   • Updated description with veo3.1 duration info (4, 6, 8 seconds)
   • Added models: veo3.1, veo3.1_fast, veo3

5. Fixed runway_generateImage

   • Added validation: Returns clear error if referenceImages is missing
   • Note: Gen4 Image models require at least 1 reference image (API limitation)

6. Build System

   • Uses SWC instead of TSC for faster, lower-memory builds
   • Works in memory-constrained environments

Tools

| Tool | Description | |------|-------------| | runway_generateVideo | Image → Video with text prompt | | runway_textToVideo | Text → Video (no image needed) ⭐ NEW | | runway_generateImage | Text + Reference Images → Image | | runway_editVideo | Video → Video editing with Aleph | | runway_upscaleVideo | Upscale video resolution | | runway_getTask | Check task status | | runway_cancelTask | Cancel/delete a task | | runway_getOrg | Get credit balance & usage |

Models

Video Generation

| Model | Type | Duration | Notes | |-------|------|----------|-------| | gen4_turbo | Image→Video | 5, 10s | Fast, default | | gen4.5 | Image→Video, Text→Video | 5, 10s | Higher quality | | gen3a_turbo | Image→Video, Text→Video | 5, 10s | Legacy | | veo3.1 | Image→Video, Text→Video | 4, 6, 8s | Best quality | | veo3.1_fast | Text→Video | 4, 6, 8s | Faster veo3.1 | | veo3 | Text→Video | 4, 6, 8s | High quality |

Image Generation

| Model | Notes | |-------|-------| | gen4_image | Default, best quality | | gen4_image_turbo | Faster | | gemini_2.5_flash | Google Gemini ⭐ NEW |

⚠️ Note: All image models require 1-3 reference images. Pure text-to-image is not supported.

Installation

npm install -g @imbsq/runway-mcp

Configuration

Set your Runway API key:

export RUNWAYML_API_SECRET="your-api-key"

Usage with MCP

Add to your MCP config (e.g., mcporter.json):

{
  "mcpServers": {
    "runway": {
      "command": "runway-mcp",
      "env": {
        "RUNWAYML_API_SECRET": "your-api-key"
      }
    }
  }
}

Examples

Text to Video (NEW)

runway_textToVideo({
  promptText: "A cat walking on the moon, cinematic",
  ratio: "1280:720",
  duration: 8,
  model: "veo3.1",
  audio: true,
  waitForCompletion: false  // returns task ID immediately
})

Image to Video (with async)

runway_generateVideo({
  promptImage: "https://example.com/image.jpg",
  promptText: "Cinematic camera movement",
  ratio: "1280:720",
  duration: 5,
  model: "gen4_turbo",
  waitForCompletion: false
})
// Returns: { "id": "task-uuid" }
// Then poll with runway_getTask({ taskId: "task-uuid" })

Image Generation (requires reference)

runway_generateImage({
  promptText: "character_a in a cyberpunk city at night",
  ratio: "1920:1080",
  model: "gen4_image",
  referenceImages: [
    { uri: "https://example.com/person.jpg", tag: "character_a" }
  ]
})

Supported Ratios

Video: 1280:720, 720:1280, 1104:832, 832:1104, 960:960, 1584:672

Image: 1920:1080, 1080:1920, 1024:1024, 1280:720, 720:1280, 1080:1080, 1168:880, 1360:768, 1440:1080, 1080:1440, 1808:768, 2112:912, 720:720, 960:720, 720:960, 1680:720

License

MIT License - see LICENSE for details.

Original work Copyright 2025 Runway AI.
Modifications Copyright 2026 BSQ.