npm package: @imbsq/runway-mcp
Description: Enhanced Runway ML MCP Server with text-to-video, async task support, and improved API coverage
Author: BSQ
Latest version: 1.0.0

# @imbsq/runway-mcp

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

> **Fork of:** [runway-api-mcp-server](https://github.com/runwayml/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

```bash
npm install -g @imbsq/runway-mcp
```

## Configuration

Set your Runway API key:

```bash
export RUNWAYML_API_SECRET="your-api-key"
```

## Usage with MCP

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

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

## Examples

### Text to Video (NEW)

```javascript
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)

```javascript
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)

```javascript
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](LICENSE) for details.

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