runway

Runway MCP

Eigener MCP (Port 8768) fuer die Runway Dev API. Use-Case: iterative B-Roll-Produktion — Still generieren → anschauen → prompten → animieren → in Remotion laden.

Source: mcp-runway (~/source/mcps/mcp-runway/).

Tools

Tool	Zweck	Input-Kernparameter
text_to_image	Still aus Prompt (Gen-4 Image)	prompt_text, ratio (siehe unten), optional reference_images, seed
image_to_video	Still → Clip (Gen-4 Turbo)	prompt_image, prompt_text (Bewegung), ratio, duration (5 oder 10)
get_task	Status + Output-URLs pollen	task_id
cancel_task	Laufenden Task abbrechen	task_id
download_output	Asset lokal speichern	task_id, output_dir (Default remotion/public/ai-broll)

Aktuell nicht gewrappt (Luecken, siehe unten): uploads, text_to_video, video_to_video (Aleph), character_performance, Audio-Endpoints, wait_for_task mit Backoff, get_organization.

Drei kritische Quirks

1. ratio ist eine Resolution, kein Aspect

Seit API-Version 2024-11-06: "1280:720" oder "1920:1080", nicht "16:9". Jedes Modell hat sein eigenes erlaubtes Set. Falsche Ratio = 400.

Modell	Erlaubte Ratios
gen4_image 720p	1280:720, 720:1280, 1104:832, 832:1104, 960:960, 1584:672
gen4_image 1080p	1920:1080, 1080:1920, 1080:1080
gen4_turbo Video	1280:720, 720:1280, 1584:672, 1104:832, 960:960, 832:1104, 480:848
gen4.5 Video	nur 1280:720 und 720:1280
gen4_aleph Video	8 Ratios inkl. 848:480 und 960:960

Faustregel: YouTube-Video → 1280:720, Hero-Still → 1920:1080, Vertical/Shorts → 720:1280.

2. Output-URLs sterben nach 24-48h

Pre-signed CloudFront-JWT in URL. Danach 403. Konsequenz:

• Nie direkt in Remotion-Timeline verlinken — sofort per download_output auf Platte ziehen
• Nie oeffentlich teilen — JWT ist sichtbar
• Nie in Tasks/Notes einfrieren — URL in TODO/PR verliert morgen Gueltigkeit

3. Moderation-Fails kosten Credits (und Account-Reputation)

Bei SAFETY.INPUT.TEXT, SAFETY.INPUT.IMAGE.* oder aehnlichen Codes: Credit nicht erstattet. Zu viele Fails → Account-Suspension.

Don’ts beim Prompten:

• Public-Figure-Namen (Prominente, Politiker, selbst tote)
• Logos / Markenzeichen im Input-Bild — triggert oft faelschlich INTERNAL.BAD_OUTPUT.01
• „generate text saying X” in der Szene — Text im Bild ist bei Gen-4 ohnehin schwach
• Child-likeness, Gewalt, NSFW = Hard-Fails

Bei SAFETY.*: nicht retryen mit demselben Prompt — Credit weg. Prompt umformulieren.

Modell-Empfehlung fuer unseren Stack

• Hero-Still: gen4_image bei 1080p, Ratio 1920:1080. 8 Credits = $0.08
• B-Roll-Clip 5-10 Sek: gen4_turbo bei 1280:720, duration 5 oder 10. 5 Credits/Sek = $0.25/Sek.5s-Clip$1.25, 10s $2.50. Bestes Preis-Leistungs-Verhaeltnis.
• Stil-Konsistenz: Reference-Images im text_to_image (bis zu 3, mit @tag-Syntax: "a man walking, @brand_style color palette, @protagonist as the character")
• Vermeiden: veo3 (40 Credits/Sek = 8x teurer), seedance2 (36 Credits/Sek), gen4.5 ohne klassische 16:9

Rate-Limits

Kein Requests-per-Minute-Cap — Concurrency-Cap pro Tier:

Tier	Parallele Tasks	Max Spend/Monat
1 (Default)	1	$50
2	5	$500
3	10	$2500

Excess → THROTTLED und queue (kein Fehler). Fuer parallele B-Roll: Tier 2 (Request via Support nach $500+ Usage).

Prompt-Patterns

• Image: [subject] [action] [setting] [style] [lighting] [camera]. Englisch. 200-400 Zeichen ideal, hartes Limit 1000.
• Video: Bild beschreiben reicht nicht — nur Bewegung. "Camera slowly zooms in. Subject turns head to the left. Gentle parallax."
• Stil-Halt: Einmal mit gen4_image Style-Anchor generieren, dann als reference_images mit @style-Tag in Folge-Prompts referenzieren
• Seed setzen fuer A/B-Varianten gleichen Prompts

Luecken im aktuellen MCP

1. upload_asset-Tool fehlt — fuer eigene lokale Hero-Stills (Midjourney/Screenshot). POST /v1/uploads dreistufiger Flow → runway://-URI als promptImage einsetzbar, 24h gueltig, max 200 MB. Hoch-priorisiert.
2. text_to_video fehlt — direkt B-Roll aus Prompt ohne Input-Bild
3. video_to_video (Aleph) fehlt — In-Context-Video-Editing
4. get_task gibt failureCode nicht zurueck — ohne Code weiss der Agent nicht ob retry-bar
5. wait_for_task mit Backoff fehlt — offizielles SDK hat Helper mit Jitter
6. get_organization fehlt — Tier + verbleibendes Budget abfragen

→ einbauen wenn Bedarf da, nicht vorher.

Setup

# 1. API-Key bei dev.runwayml.com → Account → API Keys (Billing hinterlegen)
# 2. Key in ~/source/mcps/mcp-runway/.env.local: RUNWAYML_API_SECRET=...
uv tool install --force --editable ~/source/mcps/mcp-runway
claude mcp add runway "bash ~/source/mcps/mcp-runway/start.sh"

Default-Transport: streamable-http auf 127.0.0.1:8768. Stdio: MCP_TRANSPORT=stdio.

Versioning

Pinned auf X-Runway-Version: 2024-11-06. Runway supportet alte Versionen nur 4 Monate — bei Release migrieren. Breaking Change in 2024-11-06: Ratio von Aspect zu Resolution.

Related

• mcp-runway — Source
• replicate — Alternative (Flux/SDXL/Hunyuan via Replicate)
• Runway Dev API Doku