runway-mcp

---
name: runway-mcp
description: "Run Runway's Gen-3 and Gen-4 video models from an agent — text-to-video, image-to-video, and upscaling — through Runway's official MCP server."
source: https://github.com/runwayml/runway-api-mcp-server
generated: 2026-05-28T19:59:37.331Z
category: tool
audience: ai
---

## When to use

- Generating video from a text prompt using Runway Gen-3 Alpha or Gen-4 Turbo
- Animating a reference image into video with image-to-video generation
- Upscaling an existing video to higher resolution through the agent
- Polling task status and retrieving finished video URLs without leaving the agent loop
- Building an automated creative pipeline that produces video assets programmatically

## Key concepts

### Task-based generation

Runway generation is async — create a task, get a task ID, poll until complete, then retrieve the output URL. The MCP handles all three steps as separate tool calls.

### 24-hour asset expiry

Generated video URLs expire 24 hours after creation. Download and store assets before referencing them in downstream steps.

### Model versions

Gen-3 Alpha is stable and widely supported; Gen-4 Turbo offers faster generation and higher fidelity. Specify the model when creating a task or default to the latest available.

### RUNWAYML_API_SECRET

All API calls require a Runway API secret. Store it in env and never paste or log the value in chat or generated files.

## API reference

```
git clone https://github.com/runwayml/runway-api-mcp-server && npm install && npm run build
```

Build the MCP server locally — no npm package is published, so clone and build before registering with the MCP client.

```
git clone https://github.com/runwayml/runway-api-mcp-server
cd runway-api-mcp-server
npm install && npm run build
# Then register:
claude mcp add runway \
  -e RUNWAYML_API_SECRET=key_xxx \
  -- node /path/to/runway-api-mcp-server/build/index.js
```

```
text_to_video / image_to_video / upscale_video / get_task tools
```

Use the Runway MCP tools through the client after registration. Always follow create → poll → retrieve pattern.

```
Ask the agent: "Use Runway to generate a 5-second cinematic video of a futuristic city at night, then return the download URL."
```

## Gotchas

- No npm package — must clone the repo and run npm run build before registering
- Video URLs expire after 24 hours; save outputs immediately in pipelines that run across days
- Generation is async; do not assume the video is ready in the same turn as the create call — poll until status is complete
- Do not expose RUNWAYML_API_SECRET in logs, screenshots, or generated artifacts
- Image-to-video input images must be accessible URLs or base64-encoded data — local file paths will not work

---
Generated by SkillMake from https://github.com/runwayml/runway-api-mcp-server on 2026-05-28T19:59:37.331Z.
Verify against source before relying on details.

File: ~/.claude/skills/runway-mcp/SKILL.md